annotate lispintro/emacs-lisp-intro.texi @ 65329:0f3472895e62

*** empty log message ***
author Richard M. Stallman <rms@gnu.org>
date Sun, 04 Sep 2005 01:36:02 +0000
parents 3861ff8f4bf1
children 2c8495a2cf88 2d92f5c9d6ae
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
57334
37199d6ac2c7 Add minor footnotes saying ' is an abbreviation for quote.
Robert J. Chassell <bob@rattlesnake.com>
parents: 56940
diff changeset
1 \input texinfo @c -*-texinfo-*-
41421
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
57334
37199d6ac2c7 Add minor footnotes saying ' is an abbreviation for quote.
Robert J. Chassell <bob@rattlesnake.com>
parents: 56940
diff changeset
4 @c setfilename emacs-lisp-intro.info
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5 @c sethtmlfilename emacs-lisp-intro.html
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6 @settitle Programming in Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7 @syncodeindex vr cp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8 @syncodeindex fn cp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9 @setchapternewpage odd
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10 @finalout
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12 @c ---------
41499
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
13 @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
14 @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
15 @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
16 @smallbook
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17 @clear largebook
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18 @set print-postscript-figures
41499
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
19 @c set largebook
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
20 @c clear print-postscript-figures
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21 @c ---------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
23 @comment %**end of header
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
24
57461
5e9a3ecb68cb Remember to update edition number and update-date....
Robert J. Chassell <bob@rattlesnake.com>
parents: 57460
diff changeset
25 @set edition-number 2.14
5e9a3ecb68cb Remember to update edition number and update-date....
Robert J. Chassell <bob@rattlesnake.com>
parents: 57460
diff changeset
26 @set update-date 2004 Oct 12
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
27
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
28 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
29 ## 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
30
56940
ea9bb593b003 Thanks to Christopher Allan Webber, fix typo.
Robert J. Chassell <bob@rattlesnake.com>
parents: 53099
diff changeset
31 pushd /usr/local/src/emacs/lispintro/
ea9bb593b003 Thanks to Christopher Allan Webber, fix typo.
Robert J. Chassell <bob@rattlesnake.com>
parents: 53099
diff changeset
32
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
33 ## Info output
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
34 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
35
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
36 ## DVI output
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
37 texi2dvi 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 ## HTML output
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
40 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
41
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
42 ## Plain text output
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
43 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
44 --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
45
47005
186a9c64b0fd Add version 4.2 texinfo.tex and use @copying command;
Robert J. Chassell <bob@rattlesnake.com>
parents: 46593
diff changeset
46 ## DocBook output
186a9c64b0fd Add version 4.2 texinfo.tex and use @copying command;
Robert J. Chassell <bob@rattlesnake.com>
parents: 46593
diff changeset
47 makeinfo --docbook --no-split --paragraph-indent=0 \
186a9c64b0fd Add version 4.2 texinfo.tex and use @copying command;
Robert J. Chassell <bob@rattlesnake.com>
parents: 46593
diff changeset
48 --verbose emacs-lisp-intro.texi
186a9c64b0fd Add version 4.2 texinfo.tex and use @copying command;
Robert J. Chassell <bob@rattlesnake.com>
parents: 46593
diff changeset
49
186a9c64b0fd Add version 4.2 texinfo.tex and use @copying command;
Robert J. Chassell <bob@rattlesnake.com>
parents: 46593
diff changeset
50 ## XML output
186a9c64b0fd Add version 4.2 texinfo.tex and use @copying command;
Robert J. Chassell <bob@rattlesnake.com>
parents: 46593
diff changeset
51 makeinfo --xml --no-split --paragraph-indent=0 \
186a9c64b0fd Add version 4.2 texinfo.tex and use @copying command;
Robert J. Chassell <bob@rattlesnake.com>
parents: 46593
diff changeset
52 --verbose emacs-lisp-intro.texi
186a9c64b0fd Add version 4.2 texinfo.tex and use @copying command;
Robert J. Chassell <bob@rattlesnake.com>
parents: 46593
diff changeset
53
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
54 #### (You must be in the same directory as the viewed file.)
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
55
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
56 ## View DVI output
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
57 xdvi emacs-lisp-intro.dvi &
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
58
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
59 ## View HTML output
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
60 galeon emacs-lisp-intro.html
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
61
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
62 ## View Info output with standalone reader
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
63 info emacs-lisp-intro.info
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
64
57334
37199d6ac2c7 Add minor footnotes saying ' is an abbreviation for quote.
Robert J. Chassell <bob@rattlesnake.com>
parents: 56940
diff changeset
65 ## popd
37199d6ac2c7 Add minor footnotes saying ' is an abbreviation for quote.
Robert J. Chassell <bob@rattlesnake.com>
parents: 56940
diff changeset
66
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
67 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
68
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
69 @c ================ Included Figures ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
70
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
71 @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
72 @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
73 @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
74 @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
75 @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
76
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 ================ How to Create an Info file ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
79
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
80 @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
81
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
82 @c makeinfo emacs-lisp-intro.texi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
83
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
84 @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
85 @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
86
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
87 @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
88 @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
89 @c install the manual automatically.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
90 @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
91
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
92 @c ================ How to Create an HTML file ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
93
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
94 @c To convert to HTML format
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
95 @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
96
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
97 @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
98
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
99 @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
100 @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
101
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
102 @c 7 by 9.25 inches:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
103 @c @smallbook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
104 @c @clear largebook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
105
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
106 @c 8.5 by 11 inches:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
107 @c @c smallbook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
108 @c @set largebook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
109
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
110 @c European A4 size paper:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
111 @c @c smallbook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
112 @c @afourpaper
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
113 @c @set largebook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
114
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
115 @c ================ How to Typeset and Print ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
116
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
117 @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
118 @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
119 @c system:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
120
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
121 @c texi2dvi emacs-lisp-intro.texi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
122 @c lpr -d emacs-lisp-intro.dvi
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 or else:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
125
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
126 @c tex emacs-lisp-intro.texi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
127 @c texindex emacs-lisp-intro.??
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
128 @c tex emacs-lisp-intro.texi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
129 @c lpr -d emacs-lisp-intro.dvi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
130
41499
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
131 @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
132 @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
133 @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
134 @c similar:
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
135 @c
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
136 @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
137 @c
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
138 @c or else:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
139 @c
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
140 @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
141 @c
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
142
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
143 @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
144 @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
145
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
146 @c ================ End of Formatting Sections ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
147
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
148 @c For next or subsequent edition:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
149 @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
150 @c create a major mode, with keymaps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
151 @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
152
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
153 @c For 8.5 by 11 inch format: do not use such a small amount of
46593
ddbe3ea04f58 The appropriate whitespace setting for smallbook are part of texinfo.tex.
Robert J. Chassell <bob@rattlesnake.com>
parents: 45663
diff changeset
154 @c whitespace between paragraphs as smallbook format
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
155 @ifset largebook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
156 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
157 \global\parskip 6pt plus 1pt
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
158 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
159 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
160
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
161 @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
162 @c reference with ``...'' rather than [...]
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
163
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
164 @c This works with the texinfo.tex file, version 2003-05-04.08,
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
165 @c in the Texinfo version 4.6 of the 2003 Jun 13 distribution.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
166
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
167 @tex
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
168 \global\def\xrefprintnodename#1{``#1''}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
169 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
170
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
171 @c ----------------------------------------------------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
172
41670
b4c633081255 (Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents: 41499
diff changeset
173 @dircategory Emacs
b4c633081255 (Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents: 41499
diff changeset
174 @direntry
b4c633081255 (Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents: 41499
diff changeset
175 * Emacs Lisp Intro: (eintr).
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
176 A simple introduction to Emacs Lisp programming.
41670
b4c633081255 (Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents: 41499
diff changeset
177 @end direntry
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
178
47005
186a9c64b0fd Add version 4.2 texinfo.tex and use @copying command;
Robert J. Chassell <bob@rattlesnake.com>
parents: 46593
diff changeset
179 @copying
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
180 This is an @cite{Introduction to Programming in Emacs Lisp}, for
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
181 people who are not programmers.
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
182 @sp 1
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
183 Edition @value{edition-number}, @value{update-date}
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
184 @sp 1
50622
aef53887e0ed Update copyright date and update-date.
Robert J. Chassell <bob@rattlesnake.com>
parents: 50621
diff changeset
185 Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001,
65000
3861ff8f4bf1 Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 64091
diff changeset
186 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
187 @sp 1
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
188
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
189 @iftex
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
190 Published by the:@*
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
191
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
192 GNU Press, @hfill @uref{http://www.gnupress.org}@*
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
193 a division of the @hfill General: @email{press@@gnu.org}@*
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
194 Free Software Foundation, Inc. @hfill Orders:@w{ } @email{sales@@gnu.org}@*
64083
23a17af379b1 Update FSF's address.
Lute Kamstra <lute@gnu.org>
parents: 63636
diff changeset
195 51 Franklin Street, Fifth Floor @hfill Tel: +1 (617) 542-5942@*
23a17af379b1 Update FSF's address.
Lute Kamstra <lute@gnu.org>
parents: 63636
diff changeset
196 Boston, MA 02110-1301 USA @hfill Fax: +1 (617) 542-2652@*
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
197 @end iftex
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
198
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
199 @ifnottex
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
200 Published by the:
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
201
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
202 @example
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
203 GNU Press, Website: http://www.gnupress.org
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
204 a division of the General: press@@gnu.org
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
205 Free Software Foundation, Inc. Orders: sales@@gnu.org
64083
23a17af379b1 Update FSF's address.
Lute Kamstra <lute@gnu.org>
parents: 63636
diff changeset
206 51 Franklin Street, Fifth Floor Tel: +1 (617) 542-5942
23a17af379b1 Update FSF's address.
Lute Kamstra <lute@gnu.org>
parents: 63636
diff changeset
207 Boston, MA 02110-1301 USA Fax: +1 (617) 542-2652
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
208 @end example
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
209 @end ifnottex
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
210
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
211 @sp 1
47005
186a9c64b0fd Add version 4.2 texinfo.tex and use @copying command;
Robert J. Chassell <bob@rattlesnake.com>
parents: 46593
diff changeset
212 @c Printed copies are available for $30 each.@*
186a9c64b0fd Add version 4.2 texinfo.tex and use @copying command;
Robert J. Chassell <bob@rattlesnake.com>
parents: 46593
diff changeset
213 ISBN 1-882114-43-4
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
214
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
215 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
216 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
217 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
218 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
219 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
220 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
221 Documentation License''.
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
222
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
223 (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
224 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
225 Free Software Foundation raise funds for GNU development.''
47005
186a9c64b0fd Add version 4.2 texinfo.tex and use @copying command;
Robert J. Chassell <bob@rattlesnake.com>
parents: 46593
diff changeset
226 @end copying
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 @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
229 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
230 {\begingroup%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
231 \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
232 \endgroup}%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
233 {\begingroup\hbox{}\vskip 0.25in \chaprm%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
234 \centerline{Programming in Emacs Lisp}%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
235 \endgroup\page\hbox{}\page}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
236 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
237
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
238 @titlepage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
239 @sp 6
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
240 @center @titlefont{An Introduction to}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
241 @sp 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
242 @center @titlefont{Programming in Emacs Lisp}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
243 @sp 2
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
244 @center Revised Second Edition
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
245 @sp 4
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
246 @center by Robert J. Chassell
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
247
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
248 @page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
249 @vskip 0pt plus 1filll
47005
186a9c64b0fd Add version 4.2 texinfo.tex and use @copying command;
Robert J. Chassell <bob@rattlesnake.com>
parents: 46593
diff changeset
250 @insertcopying
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
251 @end titlepage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
252
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
253 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
254 @headings off
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
255 @evenheading @thispage @| @| @thischapter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
256 @oddheading @thissection @| @| @thispage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
257 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
258
41499
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
259 @ifnothtml
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
260 @c Keep T.O.C. short by tightening up for largebook
41499
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
261 @ifset largebook
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
262 @tex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
263 \global\parskip 2pt plus 1pt
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
264 \global\advance\baselineskip by -1pt
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
265 @end tex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
266 @end ifset
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
267 @end ifnothtml
41499
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
268
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
269 @shortcontents
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
270 @contents
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
271
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
272 @ifnottex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
273 @node Top, Preface, (dir), (dir)
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
274 @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
275
47005
186a9c64b0fd Add version 4.2 texinfo.tex and use @copying command;
Robert J. Chassell <bob@rattlesnake.com>
parents: 46593
diff changeset
276 @insertcopying
41499
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
277
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
278 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
279 every node in every chapter.
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
280 @end ifnottex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
281
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
282 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
283 * Preface:: What to look for.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
284 * List Processing:: What is Lisp?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
285 * Practicing Evaluation:: Running several programs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
286 * Writing Defuns:: How to write function definitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
287 * 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
288 * 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
289 * 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
290 a region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
291 * car cdr & cons:: Fundamental functions in Lisp.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
292 * 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
293 * 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
294 * Yanking:: Pasting stored text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
295 * Loops & Recursion:: How to repeat a process.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
296 * Regexp Search:: Regular expression searches.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
297 * 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
298 * 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
299 * 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
300 * 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
301 * 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
302 * Conclusion:: Now you have the basics.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
303 * 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
304 * 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
305 * Full Graph:: How to create a graph with labelled axes.
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
306 * Free Software and Free Manuals::
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
307 * GNU Free Documentation License::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
308 * Index::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
309 * About the Author::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
310
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
311 @detailmenu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
312 --- The Detailed Node Listing ---
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
313
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
314 Preface
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
315
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
316 * Why:: Why learn Emacs Lisp?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
317 * 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
318 * 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
319 * Lisp History::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
320 * 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
321 * Thank You::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
322
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
323 List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
324
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
325 * Lisp Lists:: What are lists?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
326 * 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
327 * Making Errors:: Generating an error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
328 * 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
329 * Lisp Interpreter:: What the Lisp interpreter does.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
330 * Evaluation:: Running a program.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
331 * Variables:: Returning a value from a variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
332 * Arguments:: Passing information to a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
333 * 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
334 * Summary:: The major points.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
335 * Error Message Exercises::
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 Lisp Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
338
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
339 * 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
340 * Lisp Atoms:: Elemental entities.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
341 * 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
342 * 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
343
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
344 The Lisp Interpreter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
345
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
346 * Complications:: Variables, Special forms, Lists within.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
347 * Byte Compiling:: Specially processing code for speed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
348
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
349 Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
350
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
351 * Evaluating Inner Lists:: Lists within lists...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
352
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
353 Variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
354
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
355 * fill-column Example::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
356 * 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
357 without a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
358 * 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
359
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
360 Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
361
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
362 * 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
363 * 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
364 of a variable or list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
365 * 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
366 variable number of arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
367 * 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
368 to a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
369 * message:: A useful function for sending messages.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
370
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
371 Setting the Value of a Variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
372
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
373 * Using set:: Setting values.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
374 * Using setq:: Setting a quoted value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
375 * Counting:: Using @code{setq} to count.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
376
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
377 Practicing Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
378
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
379 * 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
380 causes evaluation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
381 * Buffer Names:: Buffers and files are different.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
382 * 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
383 * 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
384 * 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
385 the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
386 * Evaluation Exercise::
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 How To Write Function Definitions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
389
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
390 * Primitive Functions::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
391 * defun:: The @code{defun} special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
392 * Install:: Install a function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
393 * Interactive:: Making a function interactive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
394 * Interactive Options:: Different options for @code{interactive}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
395 * Permanent Installation:: Installing code permanently.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
396 * let:: Creating and initializing local variables.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
397 * if:: What if?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
398 * else:: If--then--else expressions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
399 * 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
400 * 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
401 * Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
402 * defun Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
403
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
404 Install a Function Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
405
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
406 * Effect of installation::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
407 * 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
408
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
409 Make a Function Interactive
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 * Interactive multiply-by-seven:: An overview.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
412 * 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
413
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
414 @code{let}
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 * Prevent confusion::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
417 * Parts of let Expression::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
418 * Sample let Expression::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
419 * Uninitialized let Variables::
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 The @code{if} Special Form
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 * if in more detail::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
424 * 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
425
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
426 Truth and Falsehood in Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
427
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
428 * nil explained:: @code{nil} has two meanings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
429
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
430 @code{save-excursion}
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 * 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
433 * Template for save-excursion::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
434
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
435 A Few Buffer--Related Functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
436
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
437 * Finding More:: How to find more information.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
438 * 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
439 @code{point-min}, and @code{push-mark}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
440 * 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
441 * 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
442 @code{insert-buffer-substring}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
443 * Buffer Related Review:: Review.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
444 * Buffer Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
445
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
446 The Definition of @code{mark-whole-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
447
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
448 * mark-whole-buffer overview::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
449 * 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
450
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
451 The Definition of @code{append-to-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
452
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
453 * append-to-buffer overview::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
454 * append interactive:: A two part interactive expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
455 * 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
456 * 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
457
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
458 A Few More Complex Functions
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 * 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
461 * 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
462 * beginning-of-buffer:: Shows @code{goto-char},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
463 @code{point-min}, and @code{push-mark}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
464 * Second Buffer Related Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
465 * optional Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
466
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
467 The Definition of @code{insert-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
468
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
469 * insert-buffer code::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
470 * 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
471 * 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
472 * 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
473 * 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
474 * Insert let:: Two @code{save-excursion} expressions.
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 The Interactive Expression in @code{insert-buffer}
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 * 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
479 * 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
480
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
481 Complete Definition of @code{beginning-of-buffer}
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 * Optional Arguments::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
484 * 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
485 * beginning-of-buffer complete::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
486
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
487 @code{beginning-of-buffer} with an Argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
488
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
489 * Disentangle beginning-of-buffer::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
490 * Large buffer case::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
491 * Small buffer case::
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 Narrowing and Widening
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 * Narrowing advantages:: The advantages of narrowing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
496 * 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
497 * 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
498 * narrow Exercise::
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 @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
501
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
502 * 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
503 * 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
504 * cons:: Constructing a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
505 * nthcdr:: Calling @code{cdr} repeatedly.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
506 * nth::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
507 * 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
508 * setcdr:: Changing the rest of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
509 * cons Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
510
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
511 @code{cons}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
512
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
513 * Build a list::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
514 * 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
515
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
516 Cutting and Storing Text
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 * 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
519 * 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
520 * 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
521 * 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
522 * 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
523 * 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
524 * cons & search-fwd Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
525 * search Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
526
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
527 @code{zap-to-char}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
528
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
529 * Complete zap-to-char:: The complete implementation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
530 * 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
531 * zap-to-char body:: A short overview.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
532 * 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
533 * progn:: The @code{progn} special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
534 * 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
535
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
536 @code{kill-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
537
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
538 * Complete kill-region:: The function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
539 * condition-case:: Dealing with a problem.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
540 * delete-and-extract-region:: Doing the work.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
541
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
542 Initializing a Variable with @code{defvar}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
543
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
544 * See variable current value::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
545 * defvar and asterisk:: An old-time convention.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
546
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
547 @code{copy-region-as-kill}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
548
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
549 * 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
550 * 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
551
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
552 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
553
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
554 * last-command & this-command::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
555 * kill-append function::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
556 * kill-new function::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
557
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
558 How Lists are Implemented
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
559
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
560 * Lists diagrammed::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
561 * Symbols as Chest:: Exploring a powerful metaphor.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
562 * List Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
563
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
564 Yanking Text Back
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
565
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
566 * 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
567 * 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
568 * yank nthcdr Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
569
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
570 Loops and Recursion
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 * 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
573 * dolist dotimes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
574 * Recursion:: Causing a function to call itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
575 * Looping exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
576
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
577 @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
578
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
579 * 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
580 * 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
581 * 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
582 * 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
583 * 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
584
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
585 A Loop with an Incrementing Counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
586
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
587 * Incrementing Example:: Counting pebbles in a triangle.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
588 * 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
589 * 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
590
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
591 Loop with a Decrementing Counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
592
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
593 * Decrementing Example:: More pebbles on the beach.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
594 * 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
595 * 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
596
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
597 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
598
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
599 * dolist::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
600 * dotimes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
601
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
602 Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
603
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
604 * Building Robots:: Same model, different serial number ...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
605 * Recursive Definition Parts:: Walk until you stop ...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
606 * 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
607 * Recursive triangle function::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
608 * Recursion with cond::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
609 * Recursive Patterns:: Often used templates.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
610 * No Deferment:: Don't store up work ...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
611 * No deferment solution::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
612
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
613 Recursion in Place of a Counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
614
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
615 * Recursive Example arg of 1 or 2::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
616 * Recursive Example arg of 3 or 4::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
617
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
618 Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
619
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
620 * Every::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
621 * Accumulate::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
622 * Keep::
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 Regular Expression Searches
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 * 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
627 * 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
628 * 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
629 * forward-paragraph:: A somewhat complex example.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
630 * 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
631 * Regexp Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
632 * re-search Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
633
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
634 @code{forward-sentence}
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 * Complete forward-sentence::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
637 * 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
638 * 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
639
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
640 @code{forward-paragraph}: a Goldmine of Functions
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 * 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
643 * fwd-para let:: The @code{let*} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
644 * 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
645 * fwd-para between paragraphs:: Movement between paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
646 * fwd-para within paragraph:: Movement within paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
647 * 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
648 * 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
649 * 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
650
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
651 Counting: Repetition and Regexps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
652
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
653 * Why Count Words::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
654 * 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
655 * 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
656 * Counting Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
657
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
658 The @code{count-words-region} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
659
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
660 * 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
661 * 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
662
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
663 Counting Words in a @code{defun}
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 * Divide and Conquer::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
666 * Words and Symbols:: What to count?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
667 * Syntax:: What constitutes a word or symbol?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
668 * 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
669 * 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
670 * 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
671 * 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
672 * 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
673 * 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
674 * 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
675
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
676 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
677
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
678 * 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
679 * append:: Attach one list to another.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
680
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
681 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
682
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
683 * Sorting:: Sorting lists.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
684 * Files List:: Making a list of files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
685 * Counting function definitions::
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 Readying a Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
688
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
689 * Columns of a graph::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
690 * 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
691 * recursive-graph-body-print::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
692 * Printed Axes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
693 * Line Graph Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
694
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
695 Your @file{.emacs} File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
696
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
697 * Default Configuration::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
698 * 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
699 * defcustom:: Emacs will write code for you.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
700 * 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
701 * Text and Auto-fill:: Automatically wrap lines.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
702 * Mail Aliases:: Use abbreviations for email addresses.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
703 * 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
704 * Keybindings:: Create some personal keybindings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
705 * Keymaps:: More about key binding.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
706 * 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
707 * Autoload:: Make functions available.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
708 * 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
709 * 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
710 * Miscellaneous::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
711 * 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
712
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
713 Debugging
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
714
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
715 * 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
716 * 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
717 * 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
718 * 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
719 * Debugging Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
720
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
721 Handling the Kill Ring
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 * 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
724 * 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
725 * yank-pop:: Insert first element pointed to.
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
726 * ring file::
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
727
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
728 The @code{rotate-yank-pointer} Function
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 * Understanding rotate-yk-ptr::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
731 * 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
732
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
733 The Body of @code{rotate-yank-pointer}
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 * 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
736 * 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
737 * Remainder Function:: The remainder, @code{%}, function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
738 * 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
739 * 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
740
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
741 @code{yank}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
742
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
743 * 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
744 * 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
745
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
746 A Graph with Labelled Axes
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 * Labelled Example::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
749 * 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
750 * 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
751 * print-X-axis:: Print a horizontal label.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
752 * 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
753
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
754 The @code{print-Y-axis} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
755
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
756 * 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
757 * 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
758 * 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
759 * 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
760 * 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
761
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
762 The @code{print-X-axis} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
763
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
764 * 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
765 * 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
766
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
767 Printing the Whole Graph
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 * The final version:: A few changes.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
770 * Test print-graph:: Run a short test.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
771 * 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
772 * lambda:: How to write an anonymous function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
773 * 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
774 * 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
775 * Final printed graph:: The graph itself!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
776
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
777 @end detailmenu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
778 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
779
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
780 @c >>>> Set pageno appropriately <<<<
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
781
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
782 @c The first page of the Preface is a roman numeral; it is the first
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
783 @c right handed page after the Table of Contents; hence the following
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
784 @c setting must be for an odd negative number.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
785
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
786 @iftex
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
787 @global@pageno = -11
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
788 @end iftex
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
789
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
790 @node Preface, List Processing, Top, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
791 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
792 @unnumbered Preface
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
793
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
794 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
795 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
796 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
797 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
798 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
799 extension to the editor.
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 (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
802 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
803 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
804 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
805 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
806 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
807 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
808 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
809
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
810 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
811 * Why:: Why learn Emacs Lisp?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
812 * 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
813 * 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
814 * Lisp History::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
815 * 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
816 * Thank You::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
817 @end menu
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 @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
820 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
821 @unnumberedsec Why Study Emacs Lisp?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
822 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
823
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
824 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
825 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
826 you would any other programming language.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
827
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
828 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
829 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
830 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
831 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
832 can teach yourself to go further.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
833
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
834 @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
835 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
836 @unnumberedsec On Reading this Text
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 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
839 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
840 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
841 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
842 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
843 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
844 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
845 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
846 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
847 there.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
848
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
849 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
850 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
851 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
852 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
853 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
854 implemented.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
855 Also, I
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
856 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
857 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
858 having a dragon's cave of treasures.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
859
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
860 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
861 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
862 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
863 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
864 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
865 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
866 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
867 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
868 around your home town.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
869
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
870 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
871 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
872 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
873 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
874 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
875 `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
876 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
877 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
878
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
879 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
880 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
881 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
882 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
883 advantage.
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 @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
886 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
887 @unnumberedsec For Whom This is Written
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 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
890 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
891 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
892 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
893
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
894 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
895
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
896 @quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
897 @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
898 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
899
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
900 @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
901 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
902 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
903 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
904 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
905 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
906 @end quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
907
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
908 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
909
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
910 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
911 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
912 different context, or to review it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
913
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
914 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
915 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
916 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
917 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
918 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
919 information is formally introduced.)
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 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
922 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
923 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
924 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
925 what is important, and concentrate on it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
926
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
927 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
928 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
929 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
930 as a daunting mountain.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
931
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
932 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
933 document,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
934 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
935 @cite{The GNU Emacs Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
936 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
937 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
938 @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
939 Emacs Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
940 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
941 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
942 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
943 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
944 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
945 @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
946 when you are writing your own programs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
947
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
948 @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
949 @unnumberedsec Lisp History
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
950 @cindex Lisp history
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
951
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
952 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
953 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
954 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
955 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
956
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
957 @cindex Maclisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
958 @cindex Common Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
959 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
960 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
961 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
962 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
963 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
964
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
965 @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
966 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
967 @unnumberedsec A Note for Novices
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 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
970 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
971 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
972 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
973 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
974 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
975
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
976 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
977 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
978 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
979 (@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
980 @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
981 @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
982 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
983 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
984 @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
985 (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
986 @key{ALT}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
987 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
988 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
989 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
990 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
991 @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
992 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
993 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
994 press the @key{\} key.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
995
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
996 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
997 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
998 @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
999 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
1000 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
1001 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
1002 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
1003 Numeric Arguments, emacs, The GNU Emacs Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1004
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1005 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
1006 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
1007 (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
1008
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1009 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
1010 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
1011 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
1012
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1013 @node Thank You, , Note for Novices, Preface
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1014 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1015 @unnumberedsec Thank You
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1016
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1017 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
1018 @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
1019 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
1020 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
1021 @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
1022 encouragement. My mistakes are my own.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1023
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1024 @flushright
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1025 Robert J. Chassell
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1026 @end flushright
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1027
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1028 @c ================ Beginning of main text ================
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 @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
1031
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1032 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1033 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1034 \headings off
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1035 \ifodd\pageno
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1036 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1037 \else
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1038 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1039 \page\hbox{}\page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1040 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1041 \fi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1042 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1043
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1044 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1045 @headings off
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1046 @evenheading @thispage @| @| @thischapter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1047 @oddheading @thissection @| @| @thispage
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
1048 @global@pageno = 1
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1049 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1050
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1051 @node List Processing, Practicing Evaluation, Preface, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1052 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1053 @chapter List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1054
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1055 To the untutored eye, Lisp is a strange programming language. In Lisp
57334
37199d6ac2c7 Add minor footnotes saying ' is an abbreviation for quote.
Robert J. Chassell <bob@rattlesnake.com>
parents: 56940
diff changeset
1056 code there are parentheses everywhere. Some people even claim that
37199d6ac2c7 Add minor footnotes saying ' is an abbreviation for quote.
Robert J. Chassell <bob@rattlesnake.com>
parents: 56940
diff changeset
1057 the name stands for `Lots of Isolated Silly Parentheses'. But the
37199d6ac2c7 Add minor footnotes saying ' is an abbreviation for quote.
Robert J. Chassell <bob@rattlesnake.com>
parents: 56940
diff changeset
1058 claim is unwarranted. Lisp stands for LISt Processing, and the
37199d6ac2c7 Add minor footnotes saying ' is an abbreviation for quote.
Robert J. Chassell <bob@rattlesnake.com>
parents: 56940
diff changeset
1059 programming language handles @emph{lists} (and lists of lists) by
37199d6ac2c7 Add minor footnotes saying ' is an abbreviation for quote.
Robert J. Chassell <bob@rattlesnake.com>
parents: 56940
diff changeset
1060 putting them between parentheses. The parentheses mark the boundaries
37199d6ac2c7 Add minor footnotes saying ' is an abbreviation for quote.
Robert J. Chassell <bob@rattlesnake.com>
parents: 56940
diff changeset
1061 of the list. Sometimes a list is preceded by a single apostrophe or
37199d6ac2c7 Add minor footnotes saying ' is an abbreviation for quote.
Robert J. Chassell <bob@rattlesnake.com>
parents: 56940
diff changeset
1062 quotation mark, @samp{'}@footnote{The single apostrophe or quotation
37199d6ac2c7 Add minor footnotes saying ' is an abbreviation for quote.
Robert J. Chassell <bob@rattlesnake.com>
parents: 56940
diff changeset
1063 mark is an abbreviation for the function @code{quote}; you need not
37199d6ac2c7 Add minor footnotes saying ' is an abbreviation for quote.
Robert J. Chassell <bob@rattlesnake.com>
parents: 56940
diff changeset
1064 think about functions now; functions are defined in @ref{Making
37199d6ac2c7 Add minor footnotes saying ' is an abbreviation for quote.
Robert J. Chassell <bob@rattlesnake.com>
parents: 56940
diff changeset
1065 Errors, , Generate an Error Message}.} Lists are the basis of Lisp.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1066
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1067 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1068 * Lisp Lists:: What are lists?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1069 * 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
1070 * Making Errors:: Generating an error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1071 * 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
1072 * Lisp Interpreter:: What the Lisp interpreter does.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1073 * Evaluation:: Running a program.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1074 * Variables:: Returning a value from a variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1075 * Arguments:: Passing information to a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1076 * 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
1077 * Summary:: The major points.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1078 * Error Message Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1079 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1080
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1081 @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
1082 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1083 @section Lisp Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1084 @cindex Lisp Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1085
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1086 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
1087 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
1088 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
1089 to be familiar with:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1092 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1093 '(rose
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1094 violet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1095 daisy
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1096 buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1097 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1098 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1099
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1100 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1101 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
1102 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
1103 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
1104 @cindex Flowers in a field
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1105
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1106 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1107 * 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
1108 * Lisp Atoms:: Elemental entities.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1109 * 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
1110 * 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
1111 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1112
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1113 @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
1114 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1115 @unnumberedsubsec Numbers, Lists inside of Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1116 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1117
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1118 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
1119 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
1120 separated by whitespace.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1121
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1122 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
1123 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
1124 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
1125 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
1126 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
1127 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
1128 @samp{.} as punctuation marks.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1129
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1130 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1131 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
1132
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1133 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1134 '(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
1135 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1136
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1137 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
1138 @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
1139 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
1140 @samp{of}, @samp{it}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1141
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1142 @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
1143 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1144 @subsection Lisp Atoms
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1145 @cindex Lisp Atoms
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1146
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1147 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
1148 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
1149 `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
1150 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
1151 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
1152 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
1153 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
1154 @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
1155
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1156 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
1157 right next to a parenthesis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1158
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1159 @cindex @samp{empty list} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1160 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
1161 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
1162 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
1163 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
1164 @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
1165 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
1166
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1167 @cindex Symbolic expressions, introduced
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1168 @cindex @samp{expression} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1169 @cindex @samp{form} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1170 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
1171 @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
1172 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
1173 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
1174 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
1175 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
1176 as a synonym for expression.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1177
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1178 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
1179 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
1180 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
1181 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
1182 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
1183 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
1184 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
1185 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
1186 unsplittable.
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 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
1189 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
1190 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
1191 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
1192
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1193 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
1194 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
1195 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
1196 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
1197 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
1198 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
1199 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
1200 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
1201 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
1202 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
1203 parentheses, without any non-Lisp punctuation.)
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1206 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
1207 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
1208 @cindex Text between double quotation marks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1209
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1210 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1211 '(this list includes "text between quotation marks.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1212 @end smallexample
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 @cindex @samp{string} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1215 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1216 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
1217 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
1218 @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
1219 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
1220 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
1221 used differently.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1222
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1223 @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
1224 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1225 @subsection Whitespace in Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1226 @cindex Whitespace in lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1227
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1228 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1229 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
1230 of the Lisp language,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1231
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1232 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1233 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1234 '(this list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1235 looks like this)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1236 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1237 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1238
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1239 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1240 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1241 is exactly the same as this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1242
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1243 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1244 '(this list looks like this)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1245 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1246
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1247 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
1248 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
1249 @samp{this} in that order.
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 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
1252 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
1253 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
1254 order to tell them apart.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1255
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1256 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
1257 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
1258 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
1259 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
1260 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
1261 (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
1262 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
1263
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1264 @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
1265 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1266 @subsection GNU Emacs Helps You Type Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1267 @cindex Help typing lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1268 @cindex Formatting help
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1269
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1270 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
1271 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
1272 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
1273 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
1274 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
1275 code in a region is customarily bound to @kbd{M-C-\}. Indentation is
44899
ebddb2618c17 Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 43431
diff changeset
1276 designed so that you can see which elements of a list belong to which
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1277 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
1278 the enclosing list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1279
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1280 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
1281 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
1282 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
1283 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
1284 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
1285 Manual}, for more information about Emacs' modes.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1286
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1287 @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
1288 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1289 @section Run a Program
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1290 @cindex Run a program
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1291 @cindex Program, running one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1292
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1293 @cindex @samp{evaluate} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1294 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
1295 (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
1296 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
1297 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
1298 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
1299 three things that you really want!)
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 @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
1302 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
1303 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
1304 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
1305 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
1306 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
1307 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
1308 @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
1309 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
1310 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
1311
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1312 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1313 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
1314 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
1315 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
1316
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1317 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1318 (+ 2 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1319 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1320
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1321 @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
1322 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1323 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
1324 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
1325 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
1326 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
1327 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
1328
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1329 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1330 '(this is a quoted list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1331 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1332
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1333 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1334 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
1335
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1336 @cindex Lisp interpreter, explained
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1337 @cindex Interpreter, Lisp, explained
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1338 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
1339 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
1340 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
1341 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
1342 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
1343
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1344 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
1345 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
1346 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
1347 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
1348 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
1349
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1350 @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
1351 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1352 @section Generate an Error Message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1353 @cindex Generate an error message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1354 @cindex Error message generation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1355
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1356 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
1357 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
1358 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
1359 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
1360 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
1361 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
1362 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
1363 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
1364
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1365 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
1366 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
1367
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1368 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
1369 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
1370 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
1371 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
1372 C-e}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1373
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1374 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1375 (this is an unquoted list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1376 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1377
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1378 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1379 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
1380 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
1381 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
1382 earlier, version 20 result.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1383
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1384 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1385 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1386 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
1387 you will see the following in it:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1388
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1389 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1390 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1391 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1392 Debugger entered--Lisp error: (void-function this)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1393 (this is an unquoted list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1394 eval((this is an unquoted list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1395 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1396 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1397 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1398 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1399 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1400 @end smallexample
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1403 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1404 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
1405 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
1406 debugger window go away, type:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1409 q
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1410 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1411
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1412 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1413 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
1414 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
1415 it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1416
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1417 @cindex @samp{function} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1418 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
1419
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1420 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
1421 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
1422 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
1423 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
1424 `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
1425 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
1426
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1427 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
1428 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
1429 @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
1430 backwards.
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1433 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
1434
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1435 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1436 Debugger entered--Lisp error: (void-function this)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1437 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1438
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1439 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1440 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
1441 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
1442 @samp{void-function this}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1443
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1444 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
1445
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1446 @cindex @samp{function} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1447 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
1448 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
1449 @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
1450 computer to do something.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1451
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1452 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
1453 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
1454 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
1455
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1456 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
1457 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
1458 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
1459 contain the instructions is `void'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1460
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1461 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
1462 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
1463 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
1464 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
1465
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1466 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1467 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
1468 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
1469 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1470
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1471 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1472 Symbol's function definition is void:@: this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1473 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1476 (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
1477 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
1478 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
1479
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1480 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
1481 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
1482 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
1483 (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
1484 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
1485 moment.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1486
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1487 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
1488 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
1489 @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
1490
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1491 @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
1492 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1493 @section Symbol Names and Function Definitions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1494 @cindex Symbol names
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1495
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1496 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
1497 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
1498 @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
1499 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
1500 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
1501 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
1502 work the same way. I can be referred to as @samp{Bob}; however, I am
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
1503 not the letters @samp{B}, @samp{o}, @samp{b} but am, or were, the
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
1504 consciousness consistently associated with a particular life-form.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
1505 The name is not me, but it can be used to refer to me.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1506
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1507 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
1508 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
1509 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
1510 (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
1511 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
1512
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1513 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
1514 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
1515 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
1516 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
1517 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
1518 (@xref{Install, , Install a Function Definition}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1519
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1520 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
1521 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
1522 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
1523 @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
1524 start with @samp{rmail-}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1525
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1526 @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
1527 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1528 @section The Lisp Interpreter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1529 @cindex Lisp interpreter, what it does
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1530 @cindex Interpreter, what it does
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1531
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1532 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
1533 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
1534 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
1535 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
1536 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
1537 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
1538 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
1539 Otherwise, the interpreter prints an error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1540
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1541 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
1542 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
1543 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
1544 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
1545 yourself or the computer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1546
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1547 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1548 * Complications:: Variables, Special forms, Lists within.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1549 * Byte Compiling:: Specially processing code for speed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1550 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1551
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1552 @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
1553 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1554 @unnumberedsubsec Complications
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1555 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1556
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1557 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
1558 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
1559 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
1560 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
1561 in the section on variables. (@xref{Variables}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1562
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1563 @cindex Special form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1564 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
1565 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
1566 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
1567 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
1568 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
1569
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1570 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
1571 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
1572 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
1573 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
1574 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
1575 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
1576 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
1577 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
1578 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
1579 used by the enclosing expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1580
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1581 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
1582 the next.
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 Byte Compiling, , Complications, Lisp Interpreter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1585 @subsection Byte Compiling
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1586 @cindex Byte compiling
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1587
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1588 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
1589 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
1590 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
1591 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
1592 runs faster than humanly readable code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1593
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1594 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
1595 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
1596 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
1597 @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
1598 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
1599 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
1600
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1601 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
1602 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
1603 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
1604 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
1605 compilation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1606
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1607 @node Evaluation, Variables, Lisp Interpreter, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1608 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1609 @section Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1610 @cindex Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1611
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1612 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
1613 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
1614 `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
1615 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
1616 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
1617 Collegiate Dictionary}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1618
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1619 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
1620 @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
1621 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
1622 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
1623 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
1624 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
1625 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
1626 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
1627
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1628 @cindex @samp{side effect} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1629 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
1630 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
1631 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
1632 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
1633 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
1634 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
1635
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1636 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
1637 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
1638 or else produce an error.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1639
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1640 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1641 * Evaluating Inner Lists:: Lists within lists...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1642 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1643
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1644 @node Evaluating Inner Lists, , Evaluation, Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1645 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1646 @subsection Evaluating Inner Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1647 @cindex Inner list evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1648 @cindex Evaluating inner lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1649
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1650 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
1651 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
1652 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
1653 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
1654 expressions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1655
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1656 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1657 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
1658 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
1659
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1660 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1661 (+ 2 (+ 3 3))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1662 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1663
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1664 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1665 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
1666
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1667 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
1668 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
1669 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
1670 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
1671 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
1672
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1673 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
1674 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
1675 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
1676 @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
1677 `evaluate last symbolic expression'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1678
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1679 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
1680 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
1681 expression, or inside the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1682
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1683 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1684 Here is another copy of the expression:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1687 (+ 2 (+ 3 3))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1688 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1690 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1691 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
1692 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
1693 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
1694 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
1695 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
1696 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
1697 evaluates the expression @code{(+ 3 3)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1698
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1699 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
1700 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
1701 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
1702 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
1703 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
1704 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
1705 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
1706 see in the next section.
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 @node Variables, Arguments, Evaluation, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1709 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1710 @section Variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1711 @cindex Variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1712
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1713 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
1714 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
1715 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
1716 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
1717 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
1718 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
1719 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
1720 @dfn{variable}.
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 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
1723 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
1724 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
1725 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
1726 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
1727 ``great programming center''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1728
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1729 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1730 (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
1731 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
1732 string; these are discussed later.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1733 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1734
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1735 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
1736 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
1737 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
1738 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
1739 function definition, and vice-versa.
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 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1742 * fill-column Example::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1743 * 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
1744 without a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1745 * 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
1746 @end menu
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 @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
1749 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1750 @unnumberedsubsec @code{fill-column}, an Example Variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1751 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1752
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1753 @findex fill-column, @r{an example variable}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1754 @cindex Example variable, @code{fill-column}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1755 @cindex Variable, example of, @code{fill-column}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1756 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
1757 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
1758 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
1759 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
1760 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
1761 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
1762
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1763 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1764 fill-column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1765 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1766
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1767 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1768 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
1769 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
1770 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
1771 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
1772 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
1773 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
1774 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
1775 the value is known.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1776
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1777 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
1778 @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
1779 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
1780 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
1781
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1782 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
1783 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
1784 this.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1785
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1786 @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
1787 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1788 @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
1789 @cindex Symbol without function error
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1790 @cindex Error for symbol without function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1791
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1792 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
1793 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
1794 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
1795
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1796 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
1797 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
1798 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
1799 Try evaluating this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1801 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1802 (fill-column)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1803 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1804
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1805 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1806 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1807 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
1808 that says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1809
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1810 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1811 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1812 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1813 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
1814 (fill-column)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1815 eval((fill-column))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1816 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1817 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1818 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1819 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1820 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1821 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1822
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1823 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1824 (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
1825 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
1826
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1827 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1828 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
1829
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1830 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1831 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
1832 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1833
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1834 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1835 (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
1836 another key.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1837
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1838 @node Void Variable, , Void Function, Variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1839 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1840 @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
1841 @cindex Symbol without value error
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1842 @cindex Error for symbol without value
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 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
1845 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
1846 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
1847 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
1848 type @kbd{C-x C-e}:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1851 (+ 2 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1852 @end smallexample
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 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1855 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1856 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
1857 says:
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1861 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1862 Debugger entered--Lisp error: (void-variable +)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1863 eval(+)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1864 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1865 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1866 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1867 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1868 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1869 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1870
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1871 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1872 (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
1873 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
1874
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1875 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
1876 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
1877 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
1878 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
1879 have a definition.
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 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
1882 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
1883 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
1884 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
1885 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
1886 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
1887 @code{+} by itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1888
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1889 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
1890 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
1891 variable was void.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1892
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1893 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1894 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
1895
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1896 @example
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1897 Symbol's value as variable is void:@: +
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1898 @end example
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1899
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1900 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1901 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
1902
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1903 @node Arguments, set & setq, Variables, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1904 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1905 @section Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1906 @cindex Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1907 @cindex Passing information to functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1908
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1909 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
1910 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
1911 as follows:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1912
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1913 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1914 (+ 2 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1915 @end smallexample
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 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
1918 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
1919 the @code{+}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1920
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1921 @cindex @samp{argument} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1922 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
1923 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
1924 or @dfn{passed} to the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1925
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1926 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
1927 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
1928 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
1929 @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
1930 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
1931 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
1932 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
1933 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
1934 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
1935 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
1936 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
1937 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
1938 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
1939 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
1940 `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
1941 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
1942 (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
1943 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
1944 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
1945
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1946 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1947 * 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
1948 * 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
1949 of a variable or list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1950 * 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
1951 variable number of arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1952 * 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
1953 to a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1954 * message:: A useful function for sending messages.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1955 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1956
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1957 @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
1958 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1959 @subsection Arguments' Data Types
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1960 @cindex Data types
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1961 @cindex Types of data
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1962 @cindex Arguments' data types
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1963
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1964 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
1965 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
1966 @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
1967 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
1968
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
1969 @need 1250
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1970 @findex concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1971 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
1972 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
1973 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
1974 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
1975 following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1976
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1977 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1978 (concat "abc" "def")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1979 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1980
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1981 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1982 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
1983
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1984 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
1985 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
1986 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
1987 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
1988 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
1989 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
1990 punctuations) from the beginning of the string.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1991
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1992 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1993 For example, if you evaluate the following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1994
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1995 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1996 (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
1997 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1998
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1999 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2000 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
2001 string and the two numbers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2002
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2003 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
2004 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
2005 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
2006 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
2007 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
2008 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
2009 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
2010 atom such as a number or symbol.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2011
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2012 @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
2013 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2014 @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
2015
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2016 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
2017 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
2018 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
2019
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2020 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2021 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
2022 C-e}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2023
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2024 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2025 (+ 2 fill-column)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2026 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2027
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2028 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2029 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
2030 @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
2031 @code{fill-column} is 72.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2032
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2033 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
2034 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
2035 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
2036 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
2037 @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
2038 @code{(number-to-string (+ 2 fill-column))}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2039
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2040 @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
2041 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2042 (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
2043 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2044
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2045 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2046 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
2047 @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
2048 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
2049 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
2050 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
2051 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
2052 @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
2053
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2054 @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
2055 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2056 @subsection Variable Number of Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2057 @cindex Variable number of arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2058 @cindex Arguments, variable number of
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 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
2061 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
2062 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
2063 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
2064 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
2065
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2066 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2067 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
2068
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2069 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2070 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2071 (+) @result{} 0
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 (*) @result{} 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2074 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2075 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2076
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2077 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2078 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
2079
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2080 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2081 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2082 (+ 3) @result{} 3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2083
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2084 (* 3) @result{} 3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2085 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2086 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2087
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2088 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2089 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
2090
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2091 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2092 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2093 (+ 3 4 5) @result{} 12
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2094
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2095 (* 3 4 5) @result{} 60
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2096 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2097 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2098
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2099 @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
2100 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2101 @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
2102 @cindex Wrong type of argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2103 @cindex Argument, wrong type of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2104
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2105 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
2106 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
2107 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
2108 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
2109 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
2110 @kbd{C-x C-e}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2111
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2112 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2113 (+ 2 'hello)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2114 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2115
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2116 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2117 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
2118 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
2119 @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
2120 @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
2121 could not carry out its addition.
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 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
2125 @file{*Backtrace*} buffer that says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2126
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2127 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2128 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2129 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2130 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2131 Debugger entered--Lisp error:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2132 (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
2133 +(2 hello)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2134 eval((+ 2 (quote hello)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2135 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2136 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2137 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2138 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2139 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2140 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2141
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2142 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2143 As usual, the error message tries to be helpful and makes sense after you
57334
37199d6ac2c7 Add minor footnotes saying ' is an abbreviation for quote.
Robert J. Chassell <bob@rattlesnake.com>
parents: 56940
diff changeset
2144 learn how to read it.@footnote{@code{(quote hello)} is an expansion of
37199d6ac2c7 Add minor footnotes saying ' is an abbreviation for quote.
Robert J. Chassell <bob@rattlesnake.com>
parents: 56940
diff changeset
2145 the abbreviation @code{'hello}.}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2146
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2147 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
2148 @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
2149 @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
2150 kind of argument the @code{+} expected.
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 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
2153 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
2154 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
2155 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
2156 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
2157 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
2158 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
2159 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
2160 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
2161 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
2162 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
2163 numeric value of marker positions as numbers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2164
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2165 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
2166 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
2167 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
2168 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
2169 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
2170 @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
2171 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
2172 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
2173 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
2174 @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
2175
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2176 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
2177 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
2178 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
2179 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
2180 @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
2181
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2182 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2183 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
2184 message that says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2185
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2186 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2187 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
2188 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2189
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2190 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
2191 @file{*Backtrace*} buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2192
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2193 @node message, , Wrong Type of Argument, Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2194 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2195 @subsection The @code{message} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2196 @findex message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2197
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2198 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
2199 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
2200 that we will describe it here.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2201
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2202 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2203 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
2204 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
2205
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2206 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2207 (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
2208 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2209
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2210 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
2211 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
2212 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
2213 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
2214 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
2215 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
2216 @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
2217 detail}, for an example of this.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2218
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2219 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
2220 @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
2221 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
2222 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
2223 @samp{%s} is.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2224
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2225 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2226 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
2227 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
2228
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2229 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2230 (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
2231 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2232
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2233 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2234 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
2235 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
2236 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
2237 of @code{%s}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2238
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2239 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
2240 @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
2241 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
2242
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2243 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2244 (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
2245 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2246
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2247 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2248 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
2249 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
2250 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
2251 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
2252 anything that is not a number.}.
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 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
2255 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
2256 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
2257 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
2258
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2259 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2260 For example, if you evaluate the following,
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2264 (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
2265 (- fill-column 14) "pink elephants")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2266 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2267 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2268
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2269 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2270 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
2271 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
2272
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2273 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
2274 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
2275 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
2276 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
2277 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
2278
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2279 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
2280 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
2281 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
2282 for @samp{%s}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2283
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2284 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2285 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2286 (message "He saw %d %s"
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
2287 (- fill-column 32)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2288 (concat "red "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2289 (substring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2290 "The quick brown foxes jumped." 16 21)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2291 " leaping."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2292 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2293 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2294
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2295 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
2296 @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
2297 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
2298 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
2299 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
2300 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
2301
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2302 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
2303 foxes leaping."} appears in my echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2304
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2305 @node set & setq, Summary, Arguments, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2306 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2307 @section Setting the Value of a Variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2308 @cindex Variable, setting value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2309 @cindex Setting value of variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2310
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2311 @cindex @samp{bind} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2312 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
2313 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
2314 @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
2315 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
2316
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2317 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
2318 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
2319
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2320 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2321 * Using set:: Setting values.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2322 * Using setq:: Setting a quoted value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2323 * Counting:: Using @code{setq} to count.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2324 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2325
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2326 @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
2327 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2328 @subsection Using @code{set}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2329 @findex set
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2330
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2331 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
2332 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
2333 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
2334
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2335 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2336 (set 'flowers '(rose violet daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2337 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2338
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2339 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2340 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
2341 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
2342 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
2343 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
2344 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
2345 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
2346 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
2347 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
2348 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
2349
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2350 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
2351 @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
2352 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
2353
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2354 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2355 flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2356 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2359 When you evaluate @code{flowers}, the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2360 @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
2361
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2362 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
2363 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
2364 @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
2365
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2366 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2367 'flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2368 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2369
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2370 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
2371 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
2372 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
2373 @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
2374 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
2375 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
2376 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
2377 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
2378 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
2379 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
2380 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
2381 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
2382
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2383 @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
2384 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2385 @subsection Using @code{setq}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2386 @findex setq
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2387
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2388 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
2389 @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
2390 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
2391 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
2392 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
2393 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
2394 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
2395
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2396 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
2397 @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
2398 is used:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2399
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2400 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2401 (setq carnivores '(lion tiger leopard))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2402 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2403
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2404 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2405 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
2406 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
2407 means @code{quote}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2408
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2409 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2410 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
2411
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2412 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2413 (set 'carnivores '(lion tiger leopard))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2414 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2415
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2416 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
2417 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
2418 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
2419 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
2420 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
2421 to the symbol @code{herbivores}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2422
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2423 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2424 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2425 (setq trees '(pine fir oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2426 herbivores '(gazelle antelope zebra))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2427 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2428 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2429
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2430 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2431 (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
2432 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
2433 formatted lists.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2434
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2435 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
2436 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
2437 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
2438 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
2439 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
2440 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
2441 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
2442 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
2443
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2444 @node Counting, , Using setq, set & setq
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2445 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2446 @subsection Counting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2447 @cindex Counting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2448
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2449 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
2450 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
2451 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
2452 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
2453 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
2454 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
2455 @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
2456 evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2457
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2458 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2459 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2460 (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
2461
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2462 (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
2463
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2464 counter ; @r{This is the counter.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2465 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2466 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2469 (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
2470 defun, , Change a Function Definition}.)
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 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
2473 @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
2474 @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
2475 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
2476 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
2477 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
2478 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
2479 the counter will be incremented.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2480
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2481 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
2482 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
2483 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
2484 @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
2485 @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
2486 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
2487 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
2488 @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
2489 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
2490
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2491 @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
2492 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2493 @section Summary
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2494
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2495 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
2496 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
2497 becomes easier as you progress onwards.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2498
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
2499 @need 1000
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2500 In summary,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2501
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2502 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2503
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2504 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2505 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
2506
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2507 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2508 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
2509 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
2510
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2511 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2512 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
2513 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
2514 quotation marks, or numbers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2515
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2516 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2517 A number evaluates to itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2518
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2519 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2520 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
2521
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2522 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2523 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
2524
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2525 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2526 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
2527 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
2528 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
2529
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2530 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2531 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
2532 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
2533 would if the quote were not there.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2534
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2535 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2536 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
2537 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
2538 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
2539
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2540 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2541 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
2542 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
2543 ``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
2544 create a side effect.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2545 @end itemize
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 Error Message Exercises, , Summary, 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 Exercises
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 A few simple exercises:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2552
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2553 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2554 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2555 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
2556 not within parentheses.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2557
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2558 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2559 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
2560 between parentheses.
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 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
2564
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2565 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2566 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
2567 evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2568 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2569
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2570 @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
2571 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2572 @chapter Practicing Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2573 @cindex Practicing evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2574 @cindex Evaluation practice
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2575
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2576 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
2577 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
2578 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
2579 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
2580 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
2581 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
2582 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
2583 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
2584
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2585 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2586 * 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
2587 causes evaluation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2588 * Buffer Names:: Buffers and files are different.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2589 * 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
2590 * 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
2591 * 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
2592 the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2593 * Evaluation Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2594 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2595
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2596 @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
2597 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2598 @unnumberedsec How to Evaluate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2599 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2600
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2601 @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
2602 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
2603 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
2604 how Emacs works.}
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 @cindex @samp{interactive function} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2607 @cindex @samp{command} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2608 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
2609 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
2610 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
2611 @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
2612 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
2613 @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
2614 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
2615 definitions. @xref{Interactive, , Making a Function Interactive}.
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 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
2618 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
2619 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
2620 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
2621 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
2622
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2623 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
2624 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
2625 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
2626 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
2627
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2628 @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
2629 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2630 @section Buffer Names
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2631 @findex buffer-name
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2632 @findex buffer-file-name
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2633
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2634 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
2635 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
2636 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
2637 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
2638 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
2639 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
2640 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
2641 @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
2642
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2643 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
2644 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
2645 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
2646 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
2647 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
2648 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
2649 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
2650 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
2651 and is thus saved permanently.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2652
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2653 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2654 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
2655 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
2656 typing @kbd{C-x C-e}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2657
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2658 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2659 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2660 (buffer-name)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2661
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2662 (buffer-file-name)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2663 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2664 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2665
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2666 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2667 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
2668 evaluating @code{(buffer-name)}, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2669 @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
2670 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
2671 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
2672 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
2673 @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
2674 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
2675 @xref{Variables}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2676
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2677 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
2678 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
2679 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
2680 ``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
2681 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
2682 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
2683 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
2684
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2685 @cindex Buffer, history of word
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2686 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
2687 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
2688 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
2689 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
2690 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
2691 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
2692 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
2693 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
2694 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
2695 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
2696 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
2697 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
2698 and cultural center in its own right.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2699
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2700 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
2701 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
2702 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
2703 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
2704 @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
2705
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2706 @cindex @code{nil}, history of word
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2707 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
2708 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
2709 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
2710 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
2711 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
2712 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
2713 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
2714 @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
2715 @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
2716 list, @code{()}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2717
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2718 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
2719 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
2720 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
2721 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
2722 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
2723
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2724 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2725 (buffer-name)"*scratch*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2726 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2727
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2728 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2729 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
2730 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
2731 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
2732 this book), this feature is very useful.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2733
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2734 @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
2735 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2736 @section Getting Buffers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2737 @findex current-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2738 @findex other-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2739 @cindex Getting a buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2740
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2741 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
2742 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
2743 @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
2744 you get is the buffer itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2745
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2746 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
2747 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
2748 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
2749 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
2750 @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
2751 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
2752 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
2753 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
2754 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
2755 @code{current-buffer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2756
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2757 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
2758 @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
2759 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
2760 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
2761 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
2762 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
2763 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
2764
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2765 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2766 Here is an expression containing the function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2767
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2768 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2769 (current-buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2770 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2771
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2772 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2773 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
2774 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
2775 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
2776
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2777 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
2778 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
2779 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
2780
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2781 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
2782 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
2783 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
2784 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
2785
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2786 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2787 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
2788
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2789 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2790 (other-buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2791 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2792
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2793 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2794 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
2795 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
2796 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
2797 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
2798 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
2799 subtlety that I often forget.}.
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 @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
2802 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2803 @section Switching Buffers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2804 @findex switch-to-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2805 @findex set-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2806 @cindex Switching to a buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2807
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2808 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
2809 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
2810 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
2811 different buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2812
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2813 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
2814 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
2815 @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
2816 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
2817 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
2818 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
2819 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
2820 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
2821 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
2822 interpreter to evaluate the interactive function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2823 @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
2824 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
2825 @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
2826 @code{forward-sentence}, and so on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2827
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2828 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
2829 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
2830 does.
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 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2833 Here is the Lisp expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2834
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2835 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2836 (switch-to-buffer (other-buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2837 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2838
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2839 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2840 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
2841 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
2842 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
2843 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
2844 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
2845 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
2846 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
2847 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
2848 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
2849 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
2850 (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
2851 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
2852 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
2853 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
2854 following more complex expression:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2857 (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
2858 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2859
42562
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
2860 @c noindent
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2861 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
2862 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
2863 @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
2864 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
2865 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
2866 to go to another visible 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 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
2869 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
2870 @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
2871 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
2872 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
2873 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
2874 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
2875 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
2876
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2877 @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
2878 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
2879 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
2880 @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
2881 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
2882 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
2883 there until the command finishes running).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2884
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2885 @cindex @samp{call} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2886 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
2887 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
2888 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
2889 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
2890 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
2891 or her.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2892
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2893 @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
2894 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2895 @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
2896 @cindex Size of buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2897 @cindex Buffer size
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2898 @cindex Point location
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2899 @cindex Location of point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2900
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2901 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
2902 @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
2903 @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
2904 the location of point within it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2905
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2906 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
2907 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
2908 characters in the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2909
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2910 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2911 (buffer-size)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2912 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2913
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2914 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2915 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
2916 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
2917
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2918 @cindex @samp{point} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2919 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
2920 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
2921 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
2922 beginning of the buffer up to point.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2923
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2924 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2925 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
2926 the following expression in the usual way:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2927
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2928 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2929 (point)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2930 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2933 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
2934 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
2935 book.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2936
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2937 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2938 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
2939 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
2940
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2941 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2942 (point)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2943 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2944
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2945 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2946 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
2947 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
2948
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2949 @cindex @samp{narrowing} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2950 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
2951 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
2952 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
2953 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
2954 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
2955 @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
2956 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
2957 value of point in the current buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2958
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2959 @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
2960 @section Exercise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2961
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2962 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
2963 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
2964
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2965 @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
2966 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2967 @chapter How To Write Function Definitions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2968 @cindex Definition writing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2969 @cindex Function definition writing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2970 @cindex Writing a function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2971
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2972 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
2973 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
2974 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
2975 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
2976 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
2977 (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
2978 symbol refers to it.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2979
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2980 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2981 * Primitive Functions::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2982 * defun:: The @code{defun} special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2983 * Install:: Install a function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2984 * Interactive:: Making a function interactive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2985 * Interactive Options:: Different options for @code{interactive}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2986 * Permanent Installation:: Installing code permanently.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2987 * let:: Creating and initializing local variables.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2988 * if:: What if?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2989 * else:: If--then--else expressions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2990 * 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
2991 * 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
2992 * Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2993 * defun Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2994 @end menu
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 @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
2997 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2998 @unnumberedsec An Aside about Primitive Functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2999 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3000 @cindex Primitive functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3001 @cindex Functions, primitive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3002
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3003 @cindex C language primitives
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3004 @cindex Primitives written in C
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3005 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
3006 @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
3007 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
3008 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
3009 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
3010 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
3011 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
3012 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
3013 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
3014
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3015 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
3016 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
3017 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
3018 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
3019 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
3020 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
3021
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3022 @node defun, Install, Primitive Functions, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3023 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3024 @section The @code{defun} Special Form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3025 @findex defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3026 @cindex Special form of @code{defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3027
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3028 @cindex @samp{function definition} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3029 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
3030 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
3031 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
3032 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
3033 (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
3034 @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
3035 called a @dfn{special form}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3036
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3037 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
3038 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
3039 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
3040 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
3041 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
3042 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
3043 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
3044 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
3045
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3046 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
3047 @code{defun}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3048
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3049 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3050 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3051 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
3052 attached.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3053
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3054 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3055 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
3056 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
3057 @code{()}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3058
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3059 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3060 Documentation describing the function. (Technically optional, but
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3061 strongly recommended.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3062
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3063 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3064 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
3065 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
3066 typing an appropriate key or keychord.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3067
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3068 @cindex @samp{body} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3069 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3070 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
3071 function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3072 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3073
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3074 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
3075 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
3076
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3077 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3078 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3079 (defun @var{function-name} (@var{arguments}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3080 "@var{optional-documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3081 (interactive @var{argument-passing-info}) ; @r{optional}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3082 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3083 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3084 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3085
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3086 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
3087 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
3088 , Making a Function Interactive}, for that information.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3089
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3090 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3091 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3092 (defun multiply-by-seven (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3093 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3094 (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3095 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3096 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3097
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3098 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
3099 followed by the name of the function.
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 @cindex @samp{argument list} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3102 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
3103 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
3104 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
3105 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
3106 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
3107 function.
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 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
3110 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
3111 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
3112 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
3113 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
3114 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
3115 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
3116 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
3117 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
3118 the function clear.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3119
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3120 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
3121 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
3122 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
3123 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
3124 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
3125 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
3126 `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
3127 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
3128 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
3129 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
3130 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
3131 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
3132
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3133 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3134 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
3135 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
3136 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
3137 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
3138 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
3139 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
3140 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
3141 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
3142 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
3143 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
3144 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
3145 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
3146 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3147
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3148 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
3149 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
3150 @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
3151 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
3152 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
3153 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
3154 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
3155 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
3156 (@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
3157 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
3158 write.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3159
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3160 @findex * @r{(multiplication)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3161 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
3162 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
3163 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
3164 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
3165 @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
3166 function for addition.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3167
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3168 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
3169 @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
3170 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
3171 to evaluate this yet!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3172
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3173 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3174 (multiply-by-seven 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3175 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3176
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3177 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3178 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
3179 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
3180 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
3181 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
3182 @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
3183 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
3184 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
3185 definition begins.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3186
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3187 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
3188 (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
3189 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
3190 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
3191 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
3192 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
3193 section.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3194
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3195 @node Install, Interactive, defun, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3196 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3197 @section Install a Function Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3198 @cindex Install a Function Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3199 @cindex Definition installation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3200 @cindex Function definition installation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3201
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3202 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
3203 @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
3204 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
3205 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
3206 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
3207 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
3208 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
3209 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
3210 action installs the function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3211
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3212 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3213 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3214 (defun multiply-by-seven (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3215 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3216 (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3217 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3218 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3219
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3220 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3221 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
3222 @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
3223 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
3224 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
3225 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
3226 @ref{Permanent Installation, , Installing Code Permanently}.)
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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3229 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3230 * Effect of installation::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3231 * 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
3232 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3233
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3234 @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
3235 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3236 @unnumberedsubsec The effect of installation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3237 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3238
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3239
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3240 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
3241 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
3242 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
3243 echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3244
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3245 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3246 (multiply-by-seven 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3247 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3248
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3249 If you 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
3250 @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
3251 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
3252 @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
3253
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3254 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3255 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3256 multiply-by-seven:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3257 Multiply NUMBER by seven.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3258 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3259 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3260
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3261 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3262 (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
3263
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3264 @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
3265 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3266 @subsection Change a Function Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3267 @cindex Changing a function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3268 @cindex Function definition, how to change
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3269 @cindex Definition, how to change
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3270
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3271 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
3272 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
3273 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
3274 very simple.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3275
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3276 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
3277 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
3278 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
3279 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
3280 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
3281 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
3282 version''.
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3285 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3286 (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
3287 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3288 (+ number number number number number number number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3289 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3290 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3291
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3292 @cindex Comments in Lisp code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3293 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
3294 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
3295 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
3296 each line with a semicolon.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3297
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3298 @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
3299 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
3300 Reference Manual}, for more about comments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3301
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3302 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
3303 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
3304 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
3305
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3306 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
3307 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
3308 install it again.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3309
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3310 @node Interactive, Interactive Options, Install, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3311 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3312 @section Make a Function Interactive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3313 @cindex Interactive functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3314 @findex interactive
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 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
3317 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
3318 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
3319 @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
3320 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
3321 @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
3322
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3323 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
3324 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
3325 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
3326 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
3327 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
3328 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
3329
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3330 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3331 * Interactive multiply-by-seven:: An overview.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3332 * 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
3333 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3334
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3335 @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
3336 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3337 @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
3338 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3339
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3340 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
3341 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
3342 interactive version of @code{multiply-by-seven}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3343
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3344 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3345 Here is the code:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3348 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3349 (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
3350 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3351 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3352 (message "The result is %d" (* 7 number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3353 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3354 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3355
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3356 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3357 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
3358 @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
3359 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
3360 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
3361 @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
3362 echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3363
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3364 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
3365 ways:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3366
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3367 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3368 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3369 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
3370 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
3371 @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
3372
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3373 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3374 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
3375 @kbd{C-u 3 M-e}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3376 @end enumerate
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3379 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
3380 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
3381 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
3382
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3383 (@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
3384 to a key.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3385
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3386 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
3387 @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
3388 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
3389 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
3390
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3391 @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
3392 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3393 @subsection An Interactive @code{multiply-by-seven}
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 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
3396 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
3397 @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
3398 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3399
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3400 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3401 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3402 (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
3403 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3404 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3405 (message "The result is %d" (* 7 number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3406 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3407 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3408
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3409 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
3410 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
3411 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
3412
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3413 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3414 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
3415 @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
3416
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3417 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3418 (message "The result is %d" (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3419 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3420
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3421 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3422 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3423 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
3424 evaluate the line as if it were:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3425
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3426 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3427 (message "The result is %d" (* 7 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3428 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3429
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3430 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3431 (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
3432 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
3433 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
3434 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
3435 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
3436
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3437 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
3438 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
3439 @code{message} function}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3440 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
3441 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
3442 @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
3443 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
3444 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
3445 located.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3446
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3447 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
3448 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
3449 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
3450 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
3451 is 35}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3452
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3453 (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
3454 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
3455 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
3456 @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
3457 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
3458 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
3459 quotes.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3460
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3461 @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
3462 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3463 @section Different Options for @code{interactive}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3464 @cindex Options for @code{interactive}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3465 @cindex Interactive options
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3466
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3467 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
3468 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
3469 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
3470 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
3471 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
3472 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
3473 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
3474 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
3475 @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
3476
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3477 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3478 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
3479 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
3480 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
3481
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3482 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3483 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3484 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3485
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3486 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
3487 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
3488 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
3489 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
3490 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
3491 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
3492
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3493 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
3494 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
3495 @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
3496 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
3497 @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
3498 the next part by a @samp{\n}, which is a newline. For example, you
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
3499 could follow @code{"BAppend to buffer:@: "} with a @samp{\n} and an
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3500 @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
3501 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
3502 in all.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3503
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3504 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
3505 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
3506 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
3507 beginning and ending of the region:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3508
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3509 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3510 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3511 (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
3512 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3513 (interactive "BAppend to buffer:@: \nr")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3514 @var{body-of-function}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3515 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3516 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3517
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3518 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3519 (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
3520 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
3521 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
3522 @code{append-to-buffer}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3523
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3524 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
3525 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
3526 @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
3527 this.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3528
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3529 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
3530 application, you can pass your own arguments to @code{interactive} as
53067
92487270aa3e On behalf of Kevin Ryde <user42@zip.com.au>: Corrections
Robert J. Chassell <bob@rattlesnake.com>
parents: 52401
diff changeset
3531 a list. @xref{Using Interactive, , Using @code{Interactive}, elisp, The
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3532 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
3533 technique.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3534
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3535 @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
3536 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3537 @section Install Code Permanently
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3538 @cindex Install code permanently
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3539 @cindex Permanent code installation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3540 @cindex Code installation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3541
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3542 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
3543 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
3544 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
3545 function definition again.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3546
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3547 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
3548 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
3549 doing this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3550
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3551 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3552 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3553 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
3554 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
3555 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
3556 the function definitions within it are installed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3557 @xref{Emacs Initialization, , Your @file{.emacs} File}.
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3560 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
3561 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
3562 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
3563 functions in the files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3564 @xref{Loading Files, , Loading Files}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3565
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3566 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3567 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
3568 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
3569 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
3570 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
3571 Emacs distribution.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3572 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3573
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3574 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
3575 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
3576 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
3577 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
3578 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
3579 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
3580 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
3581 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
3582 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
3583
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3584 @node let, if, Permanent Installation, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3585 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3586 @section @code{let}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3587 @findex let
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3588
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3589 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
3590 to use in most function definitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3591
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3592 @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
3593 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
3594 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
3595
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3596 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
3597 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
3598 `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
3599 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
3600 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
3601 different house.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3602
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3603 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
3604 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
3605 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
3606 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
3607 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
3608 @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
3609
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3610 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3611 * Prevent confusion::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3612 * Parts of let Expression::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3613 * Sample let Expression::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3614 * Uninitialized let Variables::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3615 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3616
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3617 @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
3618 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3619 @unnumberedsubsec @code{let} Prevents Confusion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3620 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3621
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3622 @cindex @samp{local variable} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3623 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
3624 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
3625 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
3626 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
3627 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
3628 @xref{defun, , The @code{defun} Special Form}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3629
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3630 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
3631 @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
3632 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
3633 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
3634
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3635 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
3636 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
3637 automatically undone when the @code{let} is finished. The setting
44899
ebddb2618c17 Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 43431
diff changeset
3638 only affects expressions that are inside the bounds of the @code{let}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3639 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
3640 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
3641 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
3642
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3643 @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
3644 @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
3645 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
3646 `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
3647 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
3648 @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
3649 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
3650 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
3651 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
3652 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
3653 `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
3654
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3655 @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
3656 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3657 @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
3658 @cindex @code{let} expression, parts of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3659 @cindex Parts of @code{let} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3660
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3661 @cindex @samp{varlist} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3662 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
3663 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
3664 @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
3665 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
3666 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
3667 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
3668
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3669 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3670 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
3671
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3672 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3673 (let @var{varlist} @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3674 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3675
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3676 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3677 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
3678 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
3679 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
3680 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
3681 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
3682
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3683 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
3684 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
3685 @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
3686 @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
3687
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3688 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
3689 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
3690 template.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3691
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3692 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
3693 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
3694
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3695 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3696 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3697 (let ((@var{variable} @var{value})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3698 (@var{variable} @var{value})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3699 @dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3700 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3701 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3702 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3703
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3704 @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
3705 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3706 @subsection Sample @code{let} Expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3707 @cindex Sample @code{let} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3708 @cindex @code{let} expression sample
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 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
3711 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
3712 @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
3713
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3714 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3715 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3716 (let ((zebra 'stripes)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3717 (tiger 'fierce))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3718 (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
3719 zebra tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3720 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3721 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3722
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3723 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
3724
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3725 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
3726 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
3727 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
3728 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
3729 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
3730 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
3731 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
3732 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
3733 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
3734 the echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3735
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3736 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3737 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
3738 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
3739 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
3740
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3741 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3742 "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
3743 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3744
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3745 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
3746 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
3747 @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
3748 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
3749 second @samp{%s}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3750
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3751 @node Uninitialized let Variables, , Sample let Expression, let
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3752 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3753 @subsection Uninitialized Variables in a @code{let} Statement
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3754 @cindex Uninitialized @code{let} variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3755 @cindex @code{let} variables uninitialized
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3756
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3757 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
3758 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
3759 @code{nil}, as in the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3760
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3761 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3762 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3763 (let ((birch 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3764 pine
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3765 fir
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3766 (oak 'some))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3767 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3768 "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
3769 birch pine fir oak))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3770 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3771 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3772
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3773 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3774 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
3775
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3776 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3777 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
3778 appear in your echo area:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3781 "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
3782 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3783
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3784 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3785 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
3786 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
3787 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
3788
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3789 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
3790 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
3791 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
3792 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
3793 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
3794 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
3795 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
3796 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
3797 @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
3798 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
3799
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3800 @node if, else, let, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3801 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3802 @section The @code{if} Special Form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3803 @findex if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3804 @cindex Conditional with @code{if}
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 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
3807 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
3808 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
3809 @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
3810 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
3811 function @code{beginning-of-buffer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3812
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3813 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
3814 @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
3815 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
3816 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
3817
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3818 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3819 * if in more detail::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3820 * 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
3821 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3822
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3823 @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
3824 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3825 @unnumberedsubsec @code{if} in more detail
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3826 @end ifnottex
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 @cindex @samp{if-part} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3829 @cindex @samp{then-part} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3830 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
3831 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
3832 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
3833 @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
3834 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
3835
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3836 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
3837 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
3838 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
3839 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
3840 expression easier to read.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3841
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3842 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3843 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3844 (if @var{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3845 @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
3846 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3847 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3848
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3849 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3850 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
3851 is evaluated by the Lisp interpreter.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3852
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3853 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
3854 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
3855 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
3856
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3857 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3858 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3859 (if (> 5 4) ; @r{if-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3860 (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
3861 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3862 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3863
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3864 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3865 (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
3866 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
3867 @findex > (greater than)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3868
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3869 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
3870 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
3871 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
3872 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
3873 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
3874
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3875 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
3876 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
3877 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
3878 @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
3879 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
3880
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3881 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3882 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3883 (defun type-of-animal (characteristic)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3884 "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
3885 If the CHARACTERISTIC is the symbol `fierce',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3886 then warn of a tiger."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3887 (if (equal characteristic 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3888 (message "It's a tiger!")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3889 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3890 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3891
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3892 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3893 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3894 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
3895 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
3896 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
3897
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3898 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3899 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3900 (type-of-animal 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3901
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3902 (type-of-animal 'zebra)
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 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3905 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3906
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3907 @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
3908 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3909 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
3910 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
3911 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
3912 printed in the echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3913
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3914 @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
3915 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3916 @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
3917
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3918 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
3919
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3920 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
3921 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
3922 a second for an @code{if} expression.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3925 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
3926
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3927 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3928 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3929 (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
3930 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3931 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3932 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3933 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3934
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3935 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3936 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
3937
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3938 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3939 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3940 (defun type-of-animal (characteristic)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3941 "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
3942 If the CHARACTERISTIC is the symbol `fierce',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3943 then warn of a tiger."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3944 @var{body: the} @code{if} @var{expression})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3945 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3946 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3947
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3948 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
3949 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
3950 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
3951 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
3952 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
3953 consists of the @code{if} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3954
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3955 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3956 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
3957
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3958 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3959 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3960 (if @var{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3961 @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
3962 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3963 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3964
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3965 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3966 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
3967 looks like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3970 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3971 (if (equal characteristic 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3972 (message "It's a tiger!")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3973 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3974 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3975
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3976 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3977 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
3978
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3979 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3980 (equal characteristic 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3981 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3982
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3983 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3984 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
3985 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
3986 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
3987 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
3988 this function.
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 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
3991 @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
3992 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
3993 '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
3994 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
3995 @code{(message "It's tiger!")}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3996
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3997 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
3998 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
3999 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
4000 @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
4001
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4002 @node else, Truth & Falsehood, if, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4003 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4004 @section If--then--else Expressions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4005 @cindex Else
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4006
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4007 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
4008 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
4009 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
4010 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
4011 else-part @emph{is} evaluated. You might think of this as the cloudy
57364
c14ee9d769e8 Add missing backquote.
Robert J. Chassell <bob@rattlesnake.com>
parents: 57334
diff changeset
4012 day alternative for the decision ``if it is warm and sunny, then go to
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4013 the beach, else read a book!''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4014
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4015 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
4016 @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
4017 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
4018 indented less than the then-part:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4021 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4022 (if @var{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4023 @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
4024 @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
4025 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4026 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4027
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4028 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
4029 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
4030
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4031 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4032 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4033 (if (> 4 5) ; @r{if-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4034 (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
4035 (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
4036 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4037 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4038
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4039 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4040 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
4041 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
4042 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
4043 @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
4044
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4045 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
4046 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
4047 expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4048
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4049 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4050 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
4051 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
4052 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
4053 arguments to the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4054
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4055 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4056 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4057 (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
4058 "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
4059 If the CHARACTERISTIC is the symbol `fierce',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4060 then warn of a tiger;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4061 else say it's not fierce."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4062 (if (equal characteristic 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4063 (message "It's a tiger!")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4064 (message "It's not fierce!")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4065 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4066 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4067 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4068
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4069 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4070 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4071 (type-of-animal 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4072
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4073 (type-of-animal 'zebra)
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 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4076 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4077
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4078 @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
4079 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4080 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
4081 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
4082 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
4083 @code{"It's not fierce!"}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4084
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4085 (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
4086 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
4087 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
4088 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
4089 write your program accordingly.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4090
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4091 @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
4092 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4093 @section Truth and Falsehood in Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4094 @cindex Truth and falsehood in Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4095 @cindex Falsehood and truth in Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4096 @findex nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4097
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4098 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
4099 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
4100 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
4101 `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
4102 at all---is `true'.
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 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
4105 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
4106 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
4107 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
4108 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
4109 even a buffer!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4110
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4111 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4112 * nil explained:: @code{nil} has two meanings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4113 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4114
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4115 @node nil explained, , Truth & Falsehood, Truth & Falsehood
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4116 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4117 @unnumberedsubsec An explanation of @code{nil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4118 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4119
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4120 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
4121
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4122 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
4123 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
4124 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
4125 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
4126 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
4127 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
4128
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4129 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
4130 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
4131 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
4132 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
4133 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
4134 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
4135 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
4136 list, is returned by evaluating the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4137
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4138 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
4139
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4140 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
4141 @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
4142 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
4143 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
4144 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
4145 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
4146
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4147 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4148 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4149 (if 4
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4150 'true
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4151 'false)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4152 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4153
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4154 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4155 (if nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4156 'true
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4157 'false)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4158 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4159 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4160
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4161 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4162 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
4163 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
4164 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
4165 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
4166
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4167 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4168 (> 5 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4169 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4170
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4171 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4172 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4173 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
4174
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4175 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4176 (> 4 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4177 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4178
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4179 @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
4180 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4181 @section @code{save-excursion}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4182 @findex save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4183 @cindex Region, what it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4184 @cindex Preserving point, mark, and buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4185 @cindex Point, mark, buffer preservation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4186 @findex point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4187 @findex mark
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4188
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4189 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
4190 that we will discuss in this chapter.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4191
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4192 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
4193 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
4194 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
4195 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
4196 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
4197 unexpected movement of point or mark.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4198
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4199 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4200 * 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
4201 * Template for save-excursion::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4202 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4203
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4204 @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
4205 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4206 @unnumberedsubsec Point and Mark
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4207 @end ifnottex
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 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
4210 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
4211 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
4212 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
4213 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
4214 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
4215 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
4216 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
4217 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
4218
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4219 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
4220 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
4221 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
4222 (@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
4223 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
4224 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
4225 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
4226 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
4227 times.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4228
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4229 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
4230 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
4231 @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
4232 @code{print-region}.
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 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
4235 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
4236 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
4237 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
4238 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
4239 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
4240 evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4241
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4242 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
4243 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
4244 @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
4245 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
4246 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
4247 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
4248 @code{save-excursion} is good housekeeping.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4249
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4250 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
4251 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
4252 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
4253 abnormal exit''). This feature is very helpful.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4254
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4255 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
4256 @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
4257 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
4258 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
4259 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
4260 (@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
4261
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4262 @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
4263 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4264 @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
4265
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4266 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4267 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
4268
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4269 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4270 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4271 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4272 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4273 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4274 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4275
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4276 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4277 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
4278 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
4279 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
4280 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
4281 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
4282 @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
4283 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
4284
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4285 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4286 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
4287 looks like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4290 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4291 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4292 @var{first-expression-in-body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4293 @var{second-expression-in-body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4294 @var{third-expression-in-body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4295 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4296 @var{last-expression-in-body})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4297 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4298 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4299
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4300 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4301 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
4302
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4303 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
4304 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
4305
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4306 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4307 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4308 (let @var{varlist}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4309 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4310 @var{body}@dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4311 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4312 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4313
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4314 @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
4315 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4316 @section Review
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4317
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4318 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
4319 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
4320 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
4321
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4322 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4323 @item eval-last-sexp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4324 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
4325 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
4326 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
4327 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
4328
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4329 @item defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4330 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
4331 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
4332 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
4333 definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4334
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4335 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4336 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4337
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4338 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4339 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4340 (defun back-to-indentation ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4341 "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
4342 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4343 (beginning-of-line 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4344 (skip-chars-forward " \t"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4345 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4346 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4347
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4348 @item interactive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4349 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
4350 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
4351 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
4352 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
4353 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
4354 newlines, @samp{\n}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4355
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
4356 @need 1000
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4357 Common code characters are:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4358
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4359 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4360 @item b
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4361 The name of an existing buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4362
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4363 @item f
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4364 The name of an existing file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4365
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4366 @item p
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4367 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
4368
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4369 @item r
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4370 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
4371 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
4372 rather than one.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4373 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4374
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4375 @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
4376 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
4377 code characters.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4378
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4379 @item let
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4380 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
4381 @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
4382 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
4383 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
4384 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
4385 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
4386 @code{let}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4387
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4388 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4389 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4390
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4391 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4392 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4393 (let ((foo (buffer-name))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4394 (bar (buffer-size)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4395 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4396 "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
4397 foo bar))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4398 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4399 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4400
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4401 @item save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4402 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
4403 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
4404 and mark and buffer afterward.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4405
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4406 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4407 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4408
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4409 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4410 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4411 (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
4412 (- (point)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4413 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4414 (goto-char (point-min)) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4415 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4416 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4417
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4418 @item if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4419 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
4420 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
4421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4422 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
4423 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
4424 commonly used.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4425
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4426 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4427 For example,
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4430 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4431 (if (string-equal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4432 (number-to-string 21)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4433 (substring (emacs-version) 10 12))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4434 (message "This is version 21 Emacs")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4435 (message "This is not version 21 Emacs"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4436 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4437 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4438
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4439 @item equal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4440 @itemx eq
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4441 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
4442 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
4443 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
4444 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
4445 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
4446 @findex equal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4447 @findex eq
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4448
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4449 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4450 @item <
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4451 @itemx >
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4452 @itemx <=
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4453 @itemx >=
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4454 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
4455 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
4456 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
4457 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
4458 @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
4459 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
4460 (markers indicate positions in buffers).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4461
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4462 @item string<
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4463 @itemx string-lessp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4464 @itemx string=
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4465 @itemx string-equal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4466 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
4467 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
4468 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
4469
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4470 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
4471 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
4472 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
4473
42109
24f8e84cb04d Indexed `empty string' definition.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42108
diff changeset
4474 @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
4475 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
4476 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
4477
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4478 @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
4479 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
4480 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
4481
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4482 @item message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4483 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
4484 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
4485 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
4486 be a string or a symbol; the argument used by @samp{%d} must be a
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
4487 number. The argument used by @samp{%c} must be an @sc{ascii} code
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
4488 number; it will be printed as the character with that @sc{ascii} code.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4489
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4490 @item setq
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4491 @itemx set
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4492 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
4493 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
4494 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
4495 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
4496 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
4497 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
4498
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4499 @item buffer-name
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4500 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
4501
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4502 @itemx buffer-file-name
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4503 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
4504 visiting.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4505
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4506 @item current-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4507 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
4508 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
4509
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4510 @item other-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4511 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
4512 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
4513 buffer).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4514
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4515 @item switch-to-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4516 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
4517 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
4518
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4519 @item set-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4520 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
4521 alter what the window is showing.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4522
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4523 @item buffer-size
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4524 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
4525
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4526 @item point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4527 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
4528 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
4529 buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4530
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4531 @item point-min
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4532 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
4533 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
4534
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4535 @item point-max
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4536 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
4537 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
4538 effect.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4539 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4540
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4541 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4542 @node defun Exercises, , Review, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4543 @section Exercises
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4544
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4545 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4546 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4547 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
4548 argument, a number. Make that function interactive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4549
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4550 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4551 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
4552 @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
4553 and if so, prints an appropriate message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4554 @end itemize
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 @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
4557 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4558 @chapter A Few Buffer--Related Functions
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 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
4561 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
4562 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
4563 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
4564 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
4565 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
4566 buffers. Later, we will study other functions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4567
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4568 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4569 * Finding More:: How to find more information.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4570 * 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
4571 @code{point-min}, and @code{push-mark}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4572 * 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
4573 * 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
4574 @code{insert-buffer-substring}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4575 * Buffer Related Review:: Review.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4576 * Buffer Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4577 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4578
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4579 @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
4580 @section Finding More Information
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4581
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4582 @findex describe-function, @r{introduced}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4583 @cindex Find function documentation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4584 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
4585 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
4586 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
4587 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
4588 @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
4589 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
4590 then @key{RET}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4591
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4592 @cindex Find source of function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4593 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
4594 @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
4595 function definition. If you move point over the file name and press
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
4596 the @key{RET} key, which in this case means @code{help-follow} rather
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4597 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
4598 definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4599
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4600 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
4601 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
4602 @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
4603 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
4604 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
4605 Texinfo source file of this document.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4606
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4607 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
4608 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
4609 @code{find-tags} jumps.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4610
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
4611 To use the @code{find-tags} command, type @kbd{M-.} (i.e., press the
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
4612 period key while holding down the @key{META} key, or else type the
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4613 @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
4614 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
4615 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
4616 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
4617 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
4618 @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
4619 @key{ALT}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4620
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4621 @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
4622 @cindex TAGS table, specifying
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4623 @findex find-tags
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4624 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
4625 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
4626 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
4627 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
4628 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
4629 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
4630 @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
4631 @file{/usr/local/share/emacs/21.0.100/lisp/TAGS} or
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
4632 @file{/usr/local/src/emacs/src/TAGS}. If the tags table has
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4633 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
4634
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4635 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4636 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
4637 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
4638 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
4639 @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
4640
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4641 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4642 M-x compile RET etags *.el RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4643 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4644
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4645 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
4646
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4647 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
4648 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
4649 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
4650
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4651 @cindex Library, as term for `file'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4652 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
4653 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
4654 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
4655 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
4656 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
4657 @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
4658 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
4659 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
4660 @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
4661 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
4662 @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
4663 by topic keywords.''
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 @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
4666 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4667 @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
4668 @findex simplified-beginning-of-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4669
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4670 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
4671 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
4672 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
4673 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
4674 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
4675
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4676 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
4677 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
4678 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
4679 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
4680 (@xref{beginning-of-buffer, , Complete Definition of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4681 @code{beginning-of-buffer}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4682
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4683 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
4684 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
4685 the function interactive so it can be called by typing @kbd{M-x
44899
ebddb2618c17 Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 43431
diff changeset
4686 beginning-of-buffer} or by typing a keychord such as @kbd{M-<}; it
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4687 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
4688 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
4689 of the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4690
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4691 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4692 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
4693
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4694 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4695 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4696 (defun simplified-beginning-of-buffer ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4697 "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
4698 leave mark at previous position."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4699 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4700 (push-mark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4701 (goto-char (point-min)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4702 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4703 @end smallexample
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 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
4706 the special form @code{defun}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4707
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4708 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4709 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4710 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
4711
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4712 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4713 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
4714
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4715 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4716 The documentation string.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4717
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4718 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4719 The interactive expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4720
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4721 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4722 The body.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4723 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4724
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4725 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4726 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
4727 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
4728 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
4729 an optional argument.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4730
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4731 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
4732 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
4733 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
4734 require one.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4735
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4736 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4737 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
4738
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4739 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4740 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4741 (push-mark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4742 (goto-char (point-min))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4743 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4744 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4745
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4746 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
4747 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
4748 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
4749 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
4750
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4751 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
4752 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
4753 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
4754 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
4755 Narrowing and Widening}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4756
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4757 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
4758 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
4759 @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
4760 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
4761
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4762 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
4763
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4764 @findex describe-function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4765 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
4766 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
4767 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
4768 @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
4769 @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
4770 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
4771 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
4772
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4773 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4774 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4775 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
4776 Beginning of buffer is position (point-min),
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4777 end is (point-max).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4778 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4779 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4780
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4781 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4782 (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
4783 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
4784 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
4785 @key{RET}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4786
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4787 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
4788 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
4789 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
4790 of @code{(goto-char (point-min))}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4791
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4792 @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
4793 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4794 @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
4795 @findex mark-whole-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4796
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4797 The @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
4798 @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
4799 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
4800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4801 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
4802 @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
4803 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
4804 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
4805 h}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4806
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4807
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4808 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4809 * mark-whole-buffer overview::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4810 * 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
4811 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4812
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4813
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4814 @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
4815 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4816 @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
4817 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4818
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4819 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4820 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
4821
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4822 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4823 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4824 (defun mark-whole-buffer ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4825 "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
4826 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4827 (push-mark (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4828 (push-mark (point-max))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4829 (goto-char (point-min)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4830 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4831 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4832
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4833 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4834 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
4835 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
4836 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4837
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4838 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4839 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4840 (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
4841 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4842 (@var{interactive-expression}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4843 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4844 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4845 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4846
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4847 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
4848 @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
4849 @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
4850 The documentation comes next.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4851
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4852 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
4853 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
4854 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
4855 previous section.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4856
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
4857 @need 1250
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4858 @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
4859 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4860 @subsection Body of @code{mark-whole-buffer}
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 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
4863 lines of code:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4864
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4865 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4866 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4867 (push-mark (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4868 (push-mark (point-max))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4869 (goto-char (point-min))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4870 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4871 @end smallexample
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 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
4874
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4875 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
4876 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
4877 @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
4878 at the current position of the cursor.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4879
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4880 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
4881 @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
4882 @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
4883 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
4884 @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
4885 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
4886 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
4887 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
4888 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
4889 there.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4890
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4891 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
4892 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
4893 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
4894 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
4895 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
4896 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
4897 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
4898 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
4899 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
4900 @kbd{C-u C-@key{SPC}} twice.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4901
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4902 (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
4903 complicated than shown here. The line reads
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4904
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4905 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4906 (push-mark (point-max) nil t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4907 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4908
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4909 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4910 (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
4911 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
4912 this version, @code{push-mark} has two additional arguments. The
2a4f1d831675 Fixed typographic error.
Robert J. Chassell <bob@rattlesnake.com>
parents: 41674
diff changeset
4913 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
4914 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
4915 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
4916 @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
4917 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
4918 region. It is usually turned off.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4919
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4920 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
4921 (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
4922 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
4923 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
4924 (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
4925 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
4926 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
4927 region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4928
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4929 @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
4930 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4931 @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
4932 @findex append-to-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4933
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4934 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
4935 @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
4936 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
4937 buffer to a specified buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4938
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4939 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4940 * append-to-buffer overview::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4941 * append interactive:: A two part interactive expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4942 * 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
4943 * 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
4944 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4945
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4946 @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
4947 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4948 @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
4949 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4950
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4951 @findex insert-buffer-substring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4952 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
4953 @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
4954 @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
4955 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
4956 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
4957 concerned with setting up the conditions for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4958 @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
4959 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
4960 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
4961
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4962 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4963 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4964 (defun append-to-buffer (buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4965 "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
4966 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
4967 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4968
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4969 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4970 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
4971 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
4972 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
4973 (interactive "BAppend to buffer:@: \nr")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4974 (let ((oldbuf (current-buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4975 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4976 (set-buffer (get-buffer-create buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4977 (insert-buffer-substring oldbuf start end))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4978 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4979 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4980
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4981 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
4982 filled-in templates.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4983
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4984 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
4985 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
4986
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4987 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4988 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4989 (defun append-to-buffer (buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4990 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4991 (interactive "BAppend to buffer:@: \nr")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4992 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4993 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4994 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4995
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4996 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
4997 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
4998 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
4999 will be copied.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5001 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
5002 complete.
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 @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
5005 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5006 @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
5007
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5008 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
5009 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
5010 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
5011 Function Interactive}.) The expression reads as follows:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5012
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5013 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5014 (interactive "BAppend to buffer:@: \nr")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5015 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5016
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5017 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5018 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
5019 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
5020
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5021 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
5022 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
5023 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
5024 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
5025 @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
5026 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
5027
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5028 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
5029 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
5030 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
5031 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
5032 point and mark.
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 @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
5035 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5036 @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
5037
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5038 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
5039
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5040 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
5041 @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
5042 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
5043 @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
5044 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
5045
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5046 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
5047 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
5048 @code{let} expression in outline:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5049
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5050 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5051 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5052 (defun append-to-buffer (buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5053 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5054 (interactive "BAppend to buffer:@: \nr")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5055 (let ((@var{variable} @var{value}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5056 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5057 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5058 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5059
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5060 The @code{let} expression has three elements:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5061
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5062 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5063 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5064 The symbol @code{let};
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5067 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
5068 @code{(@var{variable} @var{value})};
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5071 The body of the @code{let} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5072 @end enumerate
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5075 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
5076
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5077 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5078 (oldbuf (current-buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5079 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5082 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
5083 @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
5084 @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
5085 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
5086 which you will copy.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5087
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5088 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
5089 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
5090 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
5091 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
5092 The line looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5093
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5094 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5095 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5096 (let ((oldbuf (current-buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5097 @dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5098 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5099 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5101 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5102 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
5103 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
5104 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
5105 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
5106
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5107 @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
5108 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5109 @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
5110
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5111 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
5112 consists of a @code{save-excursion} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5113
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5114 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
5115 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
5116 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
5117 @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
5118 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
5119 @code{append-to-buffer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5120
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5121 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5122 @cindex Indentation for formatting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5123 @cindex Formatting convention
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5124 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
5125 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
5126 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
5127 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
5128 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
5129 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5130
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5131 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5132 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5133 (defun @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5134 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5135 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5136 (let@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5137 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5138 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5139 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5140 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5141
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5142 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5143 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5144 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
5145 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
5146 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
5147 @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
5148 with the @code{let}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5149
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5150 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5151 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5152 (let ((oldbuf (current-buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5153 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5154 (set-buffer (get-buffer-create buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5155 (insert-buffer-substring oldbuf start end))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5156 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5157 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5158
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5159 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5160 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
5161 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
5162
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5163 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5164 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5165 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5166 @var{first-expression-in-body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5167 @var{second-expression-in-body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5168 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5169 @var{last-expression-in-body})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5170 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5171 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5172
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5173 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5174 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5175 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
5176 two expressions. The body looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5177
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5178 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5179 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5180 (set-buffer (get-buffer-create buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5181 (insert-buffer-substring oldbuf start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5182 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5183 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5184
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5185 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
5186 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
5187 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
5188 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
5189 only for its side effects.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5190
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5191 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
5192 @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
5193 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
5194 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
5195 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
5196 primary work of the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5197
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5198 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
5199 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
5200 return.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5201
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5202 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5203 The line looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5204
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5205 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5206 (set-buffer (get-buffer-create buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5207 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5208
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5209 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
5210 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
5211 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
5212 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
5213 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
5214
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5215 @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
5216 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
5217 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
5218 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
5219 @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
5220
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5221 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5222 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
5223 the text:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5224
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5225 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5226 (insert-buffer-substring oldbuf start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5227 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5228
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5229 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5230 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
5231 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
5232 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
5233 @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
5234 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
5235 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
5236
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5237 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
5238 @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
5239 @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
5240
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5241 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5242 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
5243
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5244 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5245 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5246 (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
5247 (save-excursion ; @r{Keep track of buffer.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5248 @var{change-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5249 @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
5250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5251 @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
5252 @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
5253
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5254 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5255 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5256
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5257 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
5258 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
5259 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
5260 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
5261 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
5262 brings you back to your original buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5263
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5264 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
5265 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
5266 @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
5267 buffer. Many function definitions use @code{let},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5268 @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
5269
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5270 @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
5271 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5272 @section Review
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 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
5275
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5276 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5277 @item describe-function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5278 @itemx describe-variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5279 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
5280 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
5281
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5282 @item find-tag
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5283 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
5284 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
5285 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
5286 @key{META} key).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5287
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5288 @item save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5289 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
5290 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
5291 the current buffer and return to it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5292
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5293 @item push-mark
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5294 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
5295 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
5296 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
5297
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5298 @item goto-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5299 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
5300 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
5301 a position, such as @code{(point-min)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5302
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5303 @item insert-buffer-substring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5304 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
5305 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
5306
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5307 @item mark-whole-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5308 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
5309
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5310 @item set-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5311 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
5312 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
5313 to work on a different buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5314
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5315 @item get-buffer-create
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5316 @itemx get-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5317 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
5318 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
5319 buffer does not exist.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5320 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5321
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5322 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5323 @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
5324 @section Exercises
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5325
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5326 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5327 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5328 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
5329 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
5330
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5331 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5332 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
5333 message telling you whether a buffer exists.
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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5336 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
5337 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5338 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5339
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5340 @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
5341 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5342 @chapter A Few More Complex Functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5343
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5344 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
5345 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
5346 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
5347 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
5348 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
5349 @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
5350 to which the name refers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5351
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5352 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5353 * 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
5354 * 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
5355 * beginning-of-buffer:: Shows @code{goto-char},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5356 @code{point-min}, and @code{push-mark}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5357 * Second Buffer Related Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5358 * optional Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5359 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5360
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5361 @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
5362 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5363 @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
5364 @findex copy-to-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5365
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5366 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
5367 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
5368 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
5369 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
5370 @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
5371 @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
5372 @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
5373 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
5374 @code{append-to-buffer}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5375
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5376 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5377 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
5378
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5379 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5380 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5381 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5382 (interactive "BCopy to buffer:@: \nr")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5383 (let ((oldbuf (current-buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5384 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5385 (set-buffer (get-buffer-create buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5386 (erase-buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5387 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5388 (insert-buffer-substring oldbuf start end)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5389 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5390 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5391
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5392 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
5393 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
5394 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
5395 @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
5396 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
5397 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
5398 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
5399 @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
5400 inserted.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5401
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5402 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
5403 function does.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5406 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
5407
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5408 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5409 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5410 (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
5411 (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
5412 @var{change-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5413 (erase-buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5414 (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
5415 @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
5416 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5417 @end smallexample
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 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
5420 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
5421 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
5422 @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
5423 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
5424 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
5425 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
5426 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
5427 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
5428 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
5429 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
5430 nicety.)
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 @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
5433 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5434 @section The Definition of @code{insert-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5435 @findex insert-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5436
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5437 @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
5438 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
5439 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
5440 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
5441
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
5442 Here is a discussion based on the original code. The code was
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
5443 simplified in 2003 and is harder to understand.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
5444
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5445 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
5446 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
5447 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
5448
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5449 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5450 * insert-buffer code::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5451 * 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
5452 * 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
5453 * 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
5454 * 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
5455 * Insert let:: Two @code{save-excursion} expressions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5456 @end menu
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 @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
5459 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5460 @unnumberedsubsec The Code for @code{insert-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5461 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5462
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5463 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5464 Here is the code:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5465
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5466 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5467 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5468 (defun insert-buffer (buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5469 "Insert after point the contents of BUFFER.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5470 Puts mark after the inserted text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5471 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
5472 (interactive "*bInsert buffer:@: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5473 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5474 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5475 (or (bufferp buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5476 (setq buffer (get-buffer buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5477 (let (start end newmark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5478 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5479 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5480 (set-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5481 (setq start (point-min) end (point-max)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5482 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5483 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5484 (insert-buffer-substring buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5485 (setq newmark (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5486 (push-mark newmark)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5487 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5488 @end smallexample
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5491 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
5492 outline of the function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5493
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5494 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5495 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5496 (defun insert-buffer (buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5497 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5498 (interactive "*bInsert buffer:@: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5499 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5500 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5501 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5502
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5503 @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
5504 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5505 @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
5506 @findex interactive, @r{example use of}
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 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
5509 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
5510 buffer:@: }.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5511
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5512 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5513 * 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
5514 * 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
5515 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5516
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5517 @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
5518 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5519 @unnumberedsubsubsec A Read-only Buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5520 @cindex Read-only buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5521 @cindex Asterisk for read-only buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5522 @findex * @r{for read-only buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5523
44899
ebddb2618c17 Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 43431
diff changeset
5524 The asterisk is for the situation when the current buffer is a
ebddb2618c17 Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 43431
diff changeset
5525 read-only buffer---a buffer that cannot be modified. If
ebddb2618c17 Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 43431
diff changeset
5526 @code{insert-buffer} is called when the current buffer is read-only, a
ebddb2618c17 Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 43431
diff changeset
5527 message to this effect is printed in the echo area and the terminal
ebddb2618c17 Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 43431
diff changeset
5528 may beep or blink at you; you will not be permitted to insert anything
ebddb2618c17 Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 43431
diff changeset
5529 into current buffer. The asterisk does not need to be followed by a
ebddb2618c17 Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 43431
diff changeset
5530 newline to separate it from the next argument.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5531
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5532 @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
5533 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5534 @unnumberedsubsubsec @samp{b} in an Interactive Expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5535
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5536 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
5537 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
5538 @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
5539 @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
5540 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
5541 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
5542 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
5543 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
5544 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
5545 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
5546 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
5547
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5548 @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
5549 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5550 @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
5551
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5552 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
5553 @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
5554 @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
5555 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
5556 @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
5557 into the current buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5558
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5559 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5560 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
5561 function like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5562
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5563 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5564 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5565 (defun insert-buffer (buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5566 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5567 (interactive "*bInsert buffer:@: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5568 (or @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5569 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5570 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5571 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5572 (let (@var{varlist})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5573 @var{body-of-}@code{let}@dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5574 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5575 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5576
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5577 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
5578 @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
5579 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
5580
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5581 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
5582 @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
5583
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5584 @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
5585 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5586 @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
5587
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5588 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
5589 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
5590 then the buffer itself must be got.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5591
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5592 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
5593 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
5594 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
5595 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
5596
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5597 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5598 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
5599
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5600 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5601 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5602 (if (not (holding-on-to-guest))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5603 (find-and-take-arm-of-guest))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5604 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5605 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5606
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5607 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
5608 buffer itself, we want to get it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5609
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5610 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5611 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
5612 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
5613
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5614 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5615 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5616 (if (not (bufferp buffer)) ; @r{if-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5617 (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
5618 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5619 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5620
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5621 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5622 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
5623 @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
5624 @w{@code{(setq buffer (get-buffer buffer))}}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5625
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5626 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
5627 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
5628 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
5629 @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
5630 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
5631 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
5632 @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
5633 Argument}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5634
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5635 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5636 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
5637 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
5638
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5639 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5640 (not (bufferp buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5641 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5642
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5643 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5644 @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
5645 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
5646 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
5647 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
5648
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5649 Using this test, the @code{if} expression works as follows: when the
50621
0e3a9e34f995 Thanks to Hugo Gayosso, fix minor typos.
Robert J. Chassell <bob@rattlesnake.com>
parents: 47559
diff changeset
5650 value of the variable @code{buffer} is actually a buffer rather than
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5651 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
5652 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
5653 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
5654 a buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5655
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5656 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
5657 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
5658 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
5659 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
5660 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
5661 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
5662 @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
5663 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
5664
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5665 @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
5666 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5667 @subsection The @code{or} in the Body
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5668
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5669 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
5670 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
5671 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
5672 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
5673 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
5674 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
5675
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5676 @findex or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5677 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
5678 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
5679 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
5680 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
5681 returning the first non-@code{nil} value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5682
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5683 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5684 The @code{or} expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5685
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5686 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5687 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5688 (or (bufferp buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5689 (setq buffer (get-buffer buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5690 @end group
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 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
5695 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
5696 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
5697 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
5698 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
5699 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
5700 @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
5701
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5702 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
5703 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
5704 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
5705 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
5706 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
5707 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
5708 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
5709
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5710 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
5711 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
5712 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
5713 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
5714 buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5715
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5716 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5717 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
5718 written like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5719
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5720 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5721 (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
5722 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5723
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5724 @node Insert let, , Insert or, insert-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5725 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5726 @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
5727
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5728 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
5729 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
5730 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
5731 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
5732 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
5733 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
5734 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
5735
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5736 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5737 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
5738 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
5739 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
5740
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5741 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5742 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5743 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5744 (set-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5745 (setq start (point-min) end (point-max)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5746 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5747 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5748
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5749 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5750 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
5751 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
5752 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
5753 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
5754 @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
5755 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
5756 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
5757 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
5758 fourth.
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 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
5761 @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
5762 @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
5763 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
5764
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5765 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5766 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
5767
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5768 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5769 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5770 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5771 (@var{inner-}@code{save-excursion}@var{-expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5772 (@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
5773 (insert-buffer-substring buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5774 (setq newmark (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5775 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5776 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5779 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
5780 @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
5781 @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
5782 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
5783 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
5784 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
5785 recorded in the variable @code{newmark}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5786
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5787 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
5788 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
5789
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5790 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
5791 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
5792 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
5793 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
5794 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
5795 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
5796 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
5797 located at the beginning of the inserted text, which is where it was
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
5798 before you called the insert function, the position of which was saved
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
5799 by the first @code{save-excursion}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5801 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5802 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
5803
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5804 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5805 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5806 (let (start end newmark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5807 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5808 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5809 (set-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5810 (setq start (point-min) end (point-max)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5811 (insert-buffer-substring buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5812 (setq newmark (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5813 (push-mark newmark))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5814 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5815 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5816
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5817 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
5818 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
5819 @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
5820 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
5821 find and use again and again.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5822
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5823 @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
5824 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5825 @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
5826 @findex beginning-of-buffer
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 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
5829 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
5830 Simplified @code{beginning-of-buffer} Definition}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5831 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
5832
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5833 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
5834 @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
5835 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
5836 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
5837 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
5838 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
5839 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
5840 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
5841 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
5842 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
5843 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
5844 to the end of the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5845
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5846 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
5847 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
5848
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5849 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5850 * Optional Arguments::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5851 * 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
5852 * beginning-of-buffer complete::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5853 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5854
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5855 @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
5856 @subsection Optional Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5857
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5858 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
5859 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
5860 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
5861 @samp{Wrong number of arguments}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5862
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5863 @cindex Optional arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5864 @cindex Keyword
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5865 @findex optional
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5866 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
5867 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
5868 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
5869 @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
5870 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
5871 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
5872
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5873 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5874 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
5875 therefore looks like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5878 (defun beginning-of-buffer (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5879 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5880
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5881 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5882 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
5883
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5884 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5885 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5886 (defun beginning-of-buffer (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5887 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5888 (interactive "P")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5889 (push-mark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5890 (goto-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5891 (@var{if-there-is-an-argument}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5892 @var{figure-out-where-to-go}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5893 @var{else-go-to}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5894 (point-min))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5895 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5896 @end smallexample
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 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
5899 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
5900 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
5901 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
5902 there is an argument.
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 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
5905 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
5906 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
5907 @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
5908 defaults to 4).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5909
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5910 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
5911 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
5912 @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
5913 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
5914 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
5915 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
5916 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
5917 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
5918 @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
5919 @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
5920 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
5921 form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5922
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5923 @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
5924 @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
5925
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5926 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
5927 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
5928 @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
5929 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
5930 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5931
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5932 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5933 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5934 (if (> (buffer-size) 10000)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5935 ;; @r{Avoid overflow for large buffer sizes!}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5936 (* (prefix-numeric-value arg) (/ (buffer-size) 10))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5937 (/
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5938 (+ 10
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5939 (*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5940 (buffer-size) (prefix-numeric-value arg))) 10))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5941 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5942 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5943
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5944 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5945 * Disentangle beginning-of-buffer::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5946 * Large buffer case::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5947 * Small buffer case::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5948 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5949
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5950 @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
5951 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5952 @unnumberedsubsubsec Disentangle @code{beginning-of-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5953 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5954
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5955 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
5956 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
5957 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
5958 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
5959
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5960 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5961 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5962 (if (@var{buffer-is-large}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5963 @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
5964 @var{else-use-alternate-calculation}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5965 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5966 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5967
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5968 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
5969 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
5970 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
5971 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
5972 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
5973 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
5974 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
5975 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
5976 far larger than ever before.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5977
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5978 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
5979
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5980 @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
5981 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5982 @unnumberedsubsubsec What happens in a large buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5983
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5984 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
5985 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
5986 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
5987
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5988 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5989 The line looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5990
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5991 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5992 (if (> (buffer-size) 10000)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5993 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5994
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5995 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5996 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5997 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
5998 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
5999
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6000 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6001 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6002 (*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6003 (prefix-numeric-value arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6004 (/ (buffer-size) 10))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6005 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6006 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6007
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6008 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6009 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
6010 @code{*}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6011
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6012 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
6013 @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
6014 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
6015 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
6016 the arithmetic, a conversion is necessary, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6017 @code{prefix-numeric-value} does the job.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6018
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6019 @findex / @r{(division)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6020 @cindex Division
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6021 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
6022 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
6023 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
6024 (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
6025 used for multiplication.)
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6028 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
6029 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
6030
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6031 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6032 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6033 (* @var{numeric-value-of-prefix-arg}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6034 @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
6035 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6036 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6037
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6038 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6039 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
6040 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
6041 buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6042
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6043 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6044 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
6045 @code{goto-char} expression reads like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6046
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6047 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6048 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6049 (goto-char (* (prefix-numeric-value arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6050 (/ (buffer-size) 10)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6051 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6052 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6053
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6054 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
6055
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6056 @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
6057 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6058 @unnumberedsubsubsec What happens in a small buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6059
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6060 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
6061 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
6062 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
6063 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
6064 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
6065
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6066 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6067 The code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6068
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6069 @c Keep this on one line.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6070 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6071 (/ (+ 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
6072 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6073
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6074 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6075 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6076 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
6077 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
6078 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
6079 enclosing expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6080
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6081 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6082 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6083 (/
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6084 (+ 10
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6085 (*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6086 (buffer-size)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6087 (prefix-numeric-value arg)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6088 10))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6089 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6090 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6094 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
6095 @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
6096 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
6097 expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6098
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6099 @smallexample
56940
ea9bb593b003 Thanks to Christopher Allan Webber, fix typo.
Robert J. Chassell <bob@rattlesnake.com>
parents: 53099
diff changeset
6100 (* (buffer-size) (prefix-numeric-value arg))
41421
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6104 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
6105 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
6106 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
6107 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
6108 position in the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6109
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6110 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
6111 the cursor is moved to that point.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6112
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6113 @need 1500
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6114 @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
6115 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6116 @subsection The Complete @code{beginning-of-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6117
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6118 @need 1000
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6119 Here is the complete text of the @code{beginning-of-buffer} function:
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6120 @sp 1
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6121
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6122 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6123 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6124 (defun beginning-of-buffer (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6125 "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
6126 leave mark at previous position.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6127 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
6128 from the true beginning.
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6129 @end group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6130 @group
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6131 Don't use this in Lisp programs!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6132 \(goto-char (point-min)) is faster
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6133 and does not set the mark."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6134 (interactive "P")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6135 (push-mark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6136 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6137 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6138 (goto-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6139 (if arg
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6140 (if (> (buffer-size) 10000)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6141 ;; @r{Avoid overflow for large buffer sizes!}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6142 (* (prefix-numeric-value arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6143 (/ (buffer-size) 10))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6144 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6145 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6146 (/ (+ 10 (* (buffer-size)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6147 (prefix-numeric-value arg)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6148 10))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6149 (point-min)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6150 (if arg (forward-line 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6151 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6152 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6153
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6154 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6155 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
6156 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
6157 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
6158 the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6159
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6160 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6161 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
6162
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6163 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6164 \(goto-char (point-min))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6165 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6166
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6167 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6168 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
6169 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
6170 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
6171 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
6172
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6173 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6174 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
6175 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
6176 invoked with an argument:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6177
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6178 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6179 (if arg (forward-line 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6180 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6181
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6182 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6183 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
6184 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
6185 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
6186 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
6187 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
6188 draw complaints.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6189
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6190 @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
6191 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6192 @section Review
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6193
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6194 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
6195
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6196 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6197 @item or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6198 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
6199 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
6200 @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
6201 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
6202 other are true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6203
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6204 @item and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6205 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
6206 @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
6207 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
6208 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
6209 true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6210
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6211 @item &optional
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6212 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
6213 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
6214 argument, if desired.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6215
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6216 @item prefix-numeric-value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6217 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
6218 "P")} to a numeric value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6219
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6220 @item forward-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6221 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
6222 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
6223 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
6224 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
6225 supposed to move but couldn't.
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 @item erase-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6228 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
6229
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6230 @item bufferp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6231 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
6232 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6233
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6234 @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
6235 @section @code{optional} Argument Exercise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6236
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6237 Write an interactive function with an optional argument that tests
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6238 whether its argument, a number, is greater than or equal to, or else,
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6239 less than the value of @code{fill-column}, and tells you which, in a
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6240 message. However, if you do not pass an argument to the function, use
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6241 56 as a default value.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6242
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6243 @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
6244 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6245 @chapter Narrowing and Widening
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6246 @cindex Focusing attention (narrowing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6247 @cindex Narrowing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6248 @cindex Widening
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6249
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6250 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
6251 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
6252 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
6253 novices.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6254
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6255 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6256 * Narrowing advantages:: The advantages of narrowing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6257 * 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
6258 * 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
6259 * narrow Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6260 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6261
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6262 @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
6263 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6264 @unnumberedsec The Advantages of Narrowing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6265 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6266
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6267 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
6268 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
6269 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
6270 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
6271 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
6272 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
6273 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
6274 narrowing just to the region you want.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6275 (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
6276
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6277 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
6278 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
6279 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
6280 (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
6281 (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
6282 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
6283 @code{widen} command.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6284 (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
6285
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6286 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
6287 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
6288 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
6289 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
6290 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
6291 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
6292 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
6293 @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
6294 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
6295 situation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6296
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6297 @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
6298 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6299 @section The @code{save-restriction} Special Form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6300 @findex save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6301
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6302 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
6303 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
6304 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
6305 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
6306 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
6307 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
6308 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
6309 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
6310 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
6311 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
6312 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
6313 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6314
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6315 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6316 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
6317
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6318 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6319 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6320 (save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6321 @var{body}@dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6322 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6323 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6324
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6325 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6326 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
6327 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
6328
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6329 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
6330 @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
6331 @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
6332 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
6333 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
6334 @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
6335 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6336
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6337 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6338 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6339 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6340 (save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6341 @var{body}@dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6342 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6343 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6344
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6345 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
6346 @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
6347 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
6348
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6349 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6350 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6351
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6352 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6353 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6354 (save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6355 (widen)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6356 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6357 @var{body}@dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6358 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6359 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6360
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6361 @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
6362 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6363 @section @code{what-line}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6364 @findex what-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6365 @cindex Widening, example of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6366
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6367 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
6368 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
6369 @code{save-restriction} and @code{save-excursion} commands. Here is the
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6370 original text of the function:
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6371
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6372 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6373 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6374 (defun what-line ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6375 "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
6376 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6377 (save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6378 (widen)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6379 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6380 (beginning-of-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6381 (message "Line %d"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6382 (1+ (count-lines 1 (point)))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6383 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6384 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6385
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6386 (In recent versions of GNU Emacs, the @code{what-line} function has
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6387 been expanded to tell you your line number in a narrowed buffer as
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6388 well as your line number in a widened buffer. The recent version is
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6389 more complex than the version shown here. If you feel adventurous,
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6390 you might want to look at it after figuring out how this version
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6391 works. The newer version uses a conditional to determine whether the
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6392 buffer has been narrowed, and rather than use @code{beginning-of-line}
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6393 to move point to the beginning of the current line, if need be, the
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6394 function uses @code{(forward-line 0)}.)
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6395
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6396 The function as shown here has a documentation line and is
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6397 interactive, as you would expect. The next two lines use the
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6398 functions @code{save-restriction} and @code{widen}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6399
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6400 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
6401 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
6402 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
6403
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6404 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
6405 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
6406 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
6407 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
6408 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
6409 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
6410 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
6411 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
6412 @code{save-restriction} special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6413
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6414 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
6415 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
6416 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
6417 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
6418
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6419 (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
6420 @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
6421 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
6422 @code{save-excursion} outermost.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6423
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6424 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6425 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
6426 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
6427 echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6428
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6429 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6430 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6431 (message "Line %d"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6432 (1+ (count-lines 1 (point)))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6433 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6434 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6435
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6436 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
6437 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
6438 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
6439 @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
6440 @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
6441 something such as @samp{Line 243}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6442
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6443 @need 1200
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6444
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6445 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
6446 last line of the function:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6449 (1+ (count-lines 1 (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6450 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6451
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6452 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6453 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
6454 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
6455 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
6456 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
6457 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
6458 current line.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6459
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6460 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
6461 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
6462 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
6463 the original narrowing, if any.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6464
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6465 @node narrow Exercise, , what-line, Narrowing & Widening
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6466 @section Exercise with Narrowing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6467
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6468 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
6469 current buffer, even if you have narrowed the buffer to its latter
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6470 half so that the first line is inaccessible. Restore point, mark, and
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6471 narrowing. For this exercise, you need to use a whole potpourri of
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6472 functions, including @code{save-restriction}, @code{widen},
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6473 @code{goto-char}, @code{point-min}, @code{message}, and
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6474 @code{buffer-substring}.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6475
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6476 @cindex Properties, mention of @code{buffer-substring-no-properties}
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6477 (@code{buffer-substring} is a previously unmentioned function you will
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6478 have to investigate yourself; or perhaps you will have to use
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6479 @code{buffer-substring-no-properties} @dots{}, yet another function
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6480 and one that introduces text properties, a feature otherwise not
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6481 discussed here. @xref{Text Properties, , Text Properties, elisp, The
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6482 GNU Emacs Lisp Reference Manual}. Additionally, do you really need
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6483 @code{goto-char} or @code{point-min}? Or can you write the function
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6484 without them?)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6485
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6486 @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
6487 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6488 @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
6489 @findex car, @r{introduced}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6490 @findex cdr, @r{introduced}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6491
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6492 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
6493 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
6494 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
6495
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6496 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
6497 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
6498 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
6499
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6500 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6501 * 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
6502 * 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
6503 * cons:: Constructing a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6504 * nthcdr:: Calling @code{cdr} repeatedly.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6505 * nth::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6506 * 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
6507 * setcdr:: Changing the rest of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6508 * cons Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6509 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6510
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6511 @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
6512 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6513 @unnumberedsec Strange Names
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6514 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6515
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6516 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
6517 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
6518 @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
6519 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
6520 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
6521 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
6522 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
6523 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
6524 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
6525 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
6526 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
6527 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
6528 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
6529 introduction.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6530
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6531 @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
6532 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6533 @section @code{car} and @code{cdr}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6534
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6535 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
6536 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
6537 @code{rose}.
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6540 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
6541 evaluating the following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6542
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6543 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6544 (car '(rose violet daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6545 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6546
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6547 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6548 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
6549 area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6550
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6551 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
6552 @code{first} and this is often suggested.
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 @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
6555 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
6556 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
6557 `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
6558
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6559 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
6560 @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
6561 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
6562 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
6563 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
6564 buttercup)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6565
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6566 @need 800
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6567 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
6568
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6569 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6570 (cdr '(rose violet daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6571 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6572
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6573 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6574 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
6575 the echo area.
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 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
6578 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
6579 elements are.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6580
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6581 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
6582 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
6583 @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
6584
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6585 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
6586
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6587 (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
6588 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
6589 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
6590 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
6591 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
6592 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
6593 after you will be grateful to you.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6594
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6595 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
6596 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
6597 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
6598 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
6599 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
6600 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
6601 the usual way:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6602
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6603 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6604 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6605 (car '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6606
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6607 (cdr '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6608 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6609 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6610
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6611 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
6612 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
6613 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
6614 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
6615
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6616 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6617 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6618 (car '((lion tiger cheetah)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6619 (gazelle antelope zebra)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6620 (whale dolphin seal)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6621 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6622 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6623
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6624 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6625 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
6626 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
6627 @code{((gazelle antelope zebra) (whale dolphin seal))}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6628
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6629 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6630 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6631 (cdr '((lion tiger cheetah)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6632 (gazelle antelope zebra)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6633 (whale dolphin seal)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6634 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6635 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6636
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6637 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
6638 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
6639 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
6640
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6641 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
6642 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
6643 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
6644 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
6645 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
6646 @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
6647 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
6648 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
6649 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
6650 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
6651 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
6652 Emacs Lisp Reference Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6653
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6654 @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
6655 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6656 @section @code{cons}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6657 @findex cons, @r{introduced}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6658
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6659 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
6660 @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
6661 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
6662
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6663 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6664 (cons 'pine '(fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6665 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6666
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6667 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6668 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6669 After evaluating this list, you will see
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6670
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6671 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6672 (pine fir oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6673 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6674
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6675 @noindent
45663
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
6676 appear in the echo area. @code{cons} causes the creation of a new
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
6677 list in which the element is followed by the elements of the original
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
6678 list.
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
6679
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
6680 We often say that `@code{cons} puts a new element at the beginning of
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
6681 a list; it attaches or pushes elements onto the list', but this
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
6682 phrasing can be misleading, since @code{cons} does not change an
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
6683 existing list, but creates a new one.
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
6684
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
6685 Like @code{car} and @code{cdr}, @code{cons} is non-destructive.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6686
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6687 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6688 * Build a list::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6689 * 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
6690 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6691
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6692 @node Build a list, length, cons, cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6693 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6694 @unnumberedsubsec Build a list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6695 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6696
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6697 @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
6698 @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
6699 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
6700 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
6701 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
6702 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
6703 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
6704 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
6705 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
6706 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
6707
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6708 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6709 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6710 (cons 'buttercup ())
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6711 @result{} (buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6712 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6713
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6714 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6715 (cons 'daisy '(buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6716 @result{} (daisy buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6717 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6718
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6719 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6720 (cons 'violet '(daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6721 @result{} (violet daisy buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6722 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6723
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 'rose '(violet daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6726 @result{} (rose violet daisy 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 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6729
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6730 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6731 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
6732 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
6733 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
6734 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
6735 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
6736 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
6737
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6738 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
6739 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
6740 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
6741 @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
6742
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6743 @node length, , Build a list, cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6744 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6745 @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
6746 @findex length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6747
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6748 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
6749 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
6750
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6751 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6752 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6753 (length '(buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6754 @result{} 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6755 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6756
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6757 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6758 (length '(daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6759 @result{} 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6760 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6761
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6762 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6763 (length (cons 'violet '(daisy buttercup)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6764 @result{} 3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6765 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6766 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6767
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6768 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6769 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
6770 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
6771 its argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6772
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6773 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6774 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
6775 empty list:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6778 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6779 (length ())
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6780 @result{} 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6781 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6782 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6783
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6784 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6785 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
6786
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6787 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
6788 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
6789 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
6790
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6791 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6792 (length )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6793 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6794
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6795 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6796 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6797 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
6798
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6799 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6800 Wrong number of arguments: #<subr length>, 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6801 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6802
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6803 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6804 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
6805 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
6806 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
6807 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
6808 @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
6809
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6810 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
6811 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
6812 @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
6813 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
6814 (@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
6815 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
6816 Manual}, for more about subroutines.
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 @node nthcdr, nth, cons, car cdr & cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6819 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6820 @section @code{nthcdr}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6821 @findex nthcdr
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6822
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6823 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
6824 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
6825
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6826 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
6827 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
6828 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
6829 @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
6830 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
6831 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
6832 @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
6833 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
6834 @code{()} is shown as @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6835
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6836 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6837 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
6838 the @samp{@result{}} shows what is returned.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6839
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6840 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6841 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6842 (cdr '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6843 @result{}(fir oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6844 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6845
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6846 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6847 (cdr '(fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6848 @result{} (oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6849 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6852 (cdr '(oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6853 @result{}(maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6854 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6855
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 '(maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6858 @result{} nil
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 'nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6863 @result{} nil
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 ())
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6868 @result{} nil
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 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6871
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6872 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6873 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
6874 between, like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6877 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6878 (cdr (cdr '(pine fir oak maple)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6879 @result{} (oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6880 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6881 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6882
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6883 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6884 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
6885 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
6886 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
6887 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
6888 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
6889 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
6890 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
6891 first two elements.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6892
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6893 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
6894 @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
6895 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
6896 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
6897 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
6898
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6899 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6900 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6901 (nthcdr 2 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6902 @result{} (oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6903 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6904 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6905
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6906 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6907 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
6908 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
6909 and 5:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6910
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6911 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6912 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6913 ;; @r{Leave the list as it was.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6914 (nthcdr 0 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6915 @result{} (pine fir oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6916 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6917
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6918 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6919 ;; @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
6920 (nthcdr 1 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6921 @result{} (fir oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6922 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6923
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6924 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6925 ;; @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
6926 (nthcdr 3 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6927 @result{} (maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6928 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6929
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6930 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6931 ;; @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
6932 (nthcdr 4 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6933 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6934 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6935
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6936 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6937 ;; @r{Return a copy lacking all elements.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6938 (nthcdr 5 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6939 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6940 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6941 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6942
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6943 @node nth, setcar, nthcdr, car cdr & cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6944 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6945 @section @code{nth}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6946 @findex nth
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6947
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6948 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
6949 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
6950 @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
6951
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6952 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6953 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
6954 @code{nth} would be:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6955
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6956 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6957 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6958 (defun nth (n list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6959 "Returns the Nth element of LIST.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6960 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
6961 (car (nthcdr n list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6962 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6963 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6964
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6965 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6966 (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
6967 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
6968
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6969 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
6970 This can be very convenient.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6971
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6972 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
6973 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
6974 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
6975 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
6976 is `one-based'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6977
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6978 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6979 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6980
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6981 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6982 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6983 (nth 0 '("one" "two" "three"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6984 @result{} "one"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6985
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6986 (nth 1 '("one" "two" "three"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6987 @result{} "two"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6988 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6989 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6990
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6991 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
6992 @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
6993 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
6994 @code{setcdr} functions.
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 @node setcar, setcdr, nth, car cdr & cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6997 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6998 @section @code{setcar}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6999 @findex setcar
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 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
7002 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
7003 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
7004 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
7005 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
7006
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7007 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7008 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
7009 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
7010
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7011 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7012 (setq animals '(antelope giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7013 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7014
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7015 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7016 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
7017 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
7018 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
7019 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
7020 built into the computing environment.)
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 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
7024 the list @code{(antelope giraffe lion tiger)}:
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7028 animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7029 @result{} (antelope giraffe lion tiger)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7030 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7031 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7032
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7033 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7034 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
7035 @code{(antelope giraffe lion tiger)}.
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 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
7038 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
7039 @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
7040 @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
7041 usual fashion:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7042
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7043 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7044 (setcar animals 'hippopotamus)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7045 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7046
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7047 @need 1200
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 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
7050 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
7051
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7052 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7053 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7054 animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7055 @result{} (hippopotamus giraffe lion tiger)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7056 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7057 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7058
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7059 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7060 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
7061 @code{hippopotamus}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7062
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7063 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
7064 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
7065 @code{hippopotamus}; it @emph{changed} the list.
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 @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
7068 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7069 @section @code{setcdr}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7070 @findex setcdr
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7071
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7072 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
7073 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
7074 a list rather than the first element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7075
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
7076 (To see how to change the last element of a list, look ahead to
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
7077 @ref{kill-new function, , The @code{kill-new} function}, which uses
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
7078 the @code{nthcdr} and @code{setcdr} functions.)
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
7079
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7080 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7081 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
7082 domesticated animals by evaluating the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7083
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7084 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7085 (setq domesticated-animals '(horse cow sheep goat))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7086 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7087
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7088 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7089 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7090 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
7091 @code{(horse cow sheep goat)}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7092
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7093 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7094 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7095 domesticated-animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7096 @result{} (horse cow sheep goat)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7097 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7098 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7099
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7100 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7101 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
7102 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
7103 @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
7104
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7105 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7106 (setcdr domesticated-animals '(cat dog))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7107 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7108
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7109 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7110 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
7111 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
7112 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
7113 evaluating the variable @code{domesticated-animals}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7114
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7115 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7116 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7117 domesticated-animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7118 @result{} (horse cat dog)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7119 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7120 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7121
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7122 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7123 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
7124 @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
7125 @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
7126
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7127 @node cons Exercise, , setcdr, car cdr & cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7128 @section Exercise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7129
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7130 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
7131 @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
7132 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
7133 fish. Replace the rest of that list with a list of other fish.
44899
ebddb2618c17 Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 43431
diff changeset
7134
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7135 @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
7136 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7137 @chapter Cutting and Storing Text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7138 @cindex Cutting and storing text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7139 @cindex Storing and cutting text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7140 @cindex Killing text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7141 @cindex Clipping text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7142 @cindex Erasing text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7143 @cindex Deleting text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7144
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7145 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
7146 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
7147 `yank' command.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7148
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7149 (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
7150 @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
7151 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
7152 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
7153 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
7154 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
7155 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
7156
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7157 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7158 * 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
7159 * 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
7160 * 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
7161 * 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
7162 * 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
7163 * 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
7164 * cons & search-fwd Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7165 * search Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7166 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7167
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7168 @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
7169 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7170 @unnumberedsec Storing Text in a List
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7171 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7172
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7173 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
7174 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
7175 look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7176
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7177 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7178 ("a piece of text" "previous piece")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7179 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7180
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7181 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7182 @noindent
45663
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
7183 The function @code{cons} can be used to to create a new list from a
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
7184 piece of text (an `atom', to use the jargon) and an existing list,
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7185 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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7189 (cons "another piece"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7190 '("a piece of text" "previous piece"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7191 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7192 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7193
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7194 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7195 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7196 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
7197 the echo area:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7198
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7199 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7200 ("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
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 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
7204 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
7205 @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
7206 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
7207 second element of the original list:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7208
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7209 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7210 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7211 (car (nthcdr 1 '("another piece"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7212 "a piece of text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7213 "previous piece")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7214 @result{} "a piece of text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7215 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7216 @end smallexample
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 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
7219 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
7220 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
7221 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
7222 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
7223 than nothing at all.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7224
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7225 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
7226 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
7227 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
7228 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
7229 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
7230 climb the foothills.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7231
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7232 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
7233 retrieved. @xref{Yanking, , Yanking Text Back}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7234
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7235 @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
7236 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7237 @section @code{zap-to-char}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7238 @findex zap-to-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7239
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7240 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
7241 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
7242 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
7243 on the way to version 21.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7244
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7245 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
7246 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
7247
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7248 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
7249 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
7250 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
7251
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7252 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
7253
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7254 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7255 * Complete zap-to-char:: The complete implementation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7256 * 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
7257 * zap-to-char body:: A short overview.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7258 * 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
7259 * progn:: The @code{progn} special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7260 * 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
7261 @end menu
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 @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
7264 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7265 @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
7266 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7267
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7268 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
7269 @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
7270 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
7271 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
7272 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
7273 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
7274 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
7275 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
7276 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
7277 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
7278 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
7279 the @samp{s} in @samp{cursor}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7280
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7281 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
7282 ``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
7283 any text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7284
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7285 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
7286 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
7287 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
7288 deletion command.
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7291 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
7292
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7293 @c v 19
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7294 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7295 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7296 (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
7297 "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
7298 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
7299 (interactive "*p\ncZap to char: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7300 (kill-region (point)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7301 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7302 (search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7303 (char-to-string char) nil nil arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7304 (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7305 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7306 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7307
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7308 @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
7309 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7310 @subsection The @code{interactive} Expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7311
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7312 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7313 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
7314 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7315
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7316 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7317 (interactive "*p\ncZap to char: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7318 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7319
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7320 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
7321 three different things. First, and most simply, the asterisk, @samp{*},
63636
75c04f750f89 Fix spellings.
Juanma Barranquero <lekktu@gmail.com>
parents: 57461
diff changeset
7322 causes an error to be signaled if the buffer is read-only. This means that
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7323 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
7324 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
7325 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
7326
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7327 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
7328 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
7329 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
7330 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
7331 cases, you see an error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7332
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7333 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
7334 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
7335 @code{interactive}. According to the documentation for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7336 @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
7337 @code{zap-to-char} function from doing anything at all when the buffer
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
7338 is read only. In version 19, the function should not copy the text to
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
7339 the kill ring. It is a bug that it does.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
7340
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
7341 In version 21, the function is designed to copy the text to the kill
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
7342 ring; moreover, @code{interactive} is implemented correctly. So the
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7343 asterisk, @samp{*}, had to be removed from the interactive
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
7344 specification. However, if you insert an @samp{*} yourself and
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
7345 evaluate the function definition, then the next time you run the
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
7346 @code{zap-to-char} function on a read-only buffer, you will not copy
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
7347 any text.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7348
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7349 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
7350 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
7351
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7352 Let us continue with the interactive specification.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7353
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7354 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
7355 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
7356 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
7357 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
7358 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
7359 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
7360 this argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7361
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7362 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
7363 }. 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
7364 @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
7365 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
7366 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
7367
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7368 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
7369 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
7370
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7371 @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
7372 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7373 @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
7374
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7375 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
7376 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
7377 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
7378 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
7379
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7380 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7381 (kill-region (point) @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7382 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7383
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7384 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7385 @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
7386
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7387 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
7388 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
7389 @code{point}.
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 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
7392 @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
7393 then at @code{progn}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7394
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7395 @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
7396 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7397 @subsection The @code{search-forward} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7398 @findex search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7399
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7400 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
7401 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
7402 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
7403 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
7404 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
7405 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
7406 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
7407 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
7408
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7409 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7410 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
7411
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7412 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7413 (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
7414 @end smallexample
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 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
7417
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7418 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7419 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7420 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
7421 string, such as @samp{"z"}.
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 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
7424 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
7425 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
7426 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
7427 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
7428 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
7429 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
7430 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
7431 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
7432 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
7433 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
7434 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
7435
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7436 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7437 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
7438 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
7439 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
7440
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7441 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7442 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
7443 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
7444 @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
7445 signal an error when the search fails.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7446
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7447 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7448 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
7449 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
7450 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
7451 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
7452 backwards.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7453 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7454
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7455 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7456 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
7457
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7458 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7459 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7460 (search-forward "@var{target-string}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7461 @var{limit-of-search}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7462 @var{what-to-do-if-search-fails}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7463 @var{repeat-count})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7464 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7465 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7466
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7467 We will look at @code{progn} next.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7468
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7469 @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
7470 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7471 @subsection The @code{progn} Special Form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7472 @findex progn
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 @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
7475 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
7476 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
7477 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
7478
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7479 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7480 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
7481
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7482 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7483 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7484 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7485 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7486 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7487 @end smallexample
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 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
7490 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
7491 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
7492
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7493 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
7494 @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
7495 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
7496 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
7497 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
7498 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
7499
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7500 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
7501 @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
7502 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
7503 @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
7504 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
7505 second argument.
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 @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
7508 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7509 @subsection Summing up @code{zap-to-char}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7510
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7511 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
7512 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
7513
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7514 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
7515 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
7516 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
7517 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
7518 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
7519 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
7520 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
7521
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7522 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
7523 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
7524 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
7525 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
7526 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
7527 needs for its second argument.
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 @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
7530 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7531 @section @code{kill-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7532 @findex kill-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7533
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7534 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
7535 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
7536 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
7537
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7538 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
7539 @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
7540 @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
7541
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7542 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
7543 @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
7544 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
7545 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
7546 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
7547
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7548 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7549 * Complete kill-region:: The function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7550 * condition-case:: Dealing with a problem.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7551 * delete-and-extract-region:: Doing the work.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7552 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7553
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7554 @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
7555 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7556 @unnumberedsubsec The Complete @code{kill-region} Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7557 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7558
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7559 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7560 We will go through the @code{condition-case} code in a moment. First,
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
7561 let us look at the original definition of @code{kill-region}, with
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
7562 comments added (the newer definition has an optional third argument
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
7563 and is more complex):
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7564
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7565 @c v 21
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7566 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7567 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7568 (defun kill-region (beg end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7569 "Kill between point and mark.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7570 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
7571 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7572 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7573
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7574 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7575 ;; 1. `condition-case' takes three arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7576 ;; 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
7577 ;; information about the error signal is not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7578 ;; stored for use by another function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7579 (condition-case nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7580 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7581
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7582 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7583 ;; 2. The second argument to `condition-case'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7584 ;; 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
7585 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7586
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7587 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7588 ;; 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
7589 ;; 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
7590 ;; 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
7591 (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
7592 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7593
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7594 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7595 ;; `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
7596 ;; 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
7597 ;; previous command.
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7600 ;; `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
7601 ;; `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
7602 (when string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7603 (if (eq last-command 'kill-region)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7604 ;; if true, prepend string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7605 (kill-append string (< end beg))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7606 (kill-new string)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7607 (setq this-command 'kill-region))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7608 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7609
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7610 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7611 ;; 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
7612 ;; what to do with an error.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7613 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7614 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7615 ;; 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
7616 ;; 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
7617 ;; if text or buffer is read-only)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7618 ;; then the body is executed.
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 ((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
7622 ;; then...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7623 (copy-region-as-kill beg end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7624 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7625 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7626 (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
7627 (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
7628 ;; 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
7629 (barf-if-buffer-read-only)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7630 ;; 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
7631 (signal 'text-read-only (list (current-buffer)))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7632 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7633 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7634
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7635 @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
7636 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7637 @subsection @code{condition-case}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7638 @findex condition-case
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7639
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7640 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
7641 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
7642 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
7643 ``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
7644 shows you a message.
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 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
7647 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
7648 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
7649 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
7650 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
7651 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
7652 special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7653
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7654 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7655 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
7656
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7657 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7658 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7659 (condition-case
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7660 @var{var}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7661 @var{bodyform}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7662 @var{error-handler}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7663 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7664 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7665
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7666 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
7667 @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
7668 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
7669 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
7670
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7671 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
7672 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
7673 correctly.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7674
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7675 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
7676 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
7677 names.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7678
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7679 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
7680 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
7681 @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
7682 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
7683 part of the error handler is run.
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 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
7686 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
7687
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7688 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
7689 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
7690 handler is run.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7691
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7692 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
7693 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
7694 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
7695 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
7696 discarded.
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7699 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
7700 @code{condition-case} works like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7701
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7702 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7703 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7704 @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
7705 @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
7706 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7707 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7708
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7709 @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
7710 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7711 @subsection @code{delete-and-extract-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7712 @findex delete-and-extract-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7713
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7714 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
7715 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
7716 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
7717 error.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7718
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7719 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
7720 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
7721 The code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7722
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7723 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7724 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7725 (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
7726 (when string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7727 (if (eq last-command 'kill-region)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7728 (kill-append string (< end beg))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7729 (kill-new string)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7730 (setq this-command 'kill-region))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7731 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7732 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7733
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7734 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
7735 @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
7736 @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
7737 @code{last-command} and @code{this-command}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7738
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7739 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
7740 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
7741 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
7742 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
7743 error.)
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 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
7746 @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
7747 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
7748 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
7749 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
7750 is simply a shorthand.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7751
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7752 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
7753 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
7754 text was removed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7755
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7756 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
7757 @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
7758 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
7759 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
7760 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
7761 That is what the Lisp interpreter does.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7762
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7763 @cindex Macro, lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7764 @cindex Lisp macro
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7765 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
7766 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
7767 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
7768 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
7769 `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
7770 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
7771 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
7772 different, but also useful. We will briefly look at C macros in
45663
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
7773 @ref{Digression into C}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7774
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7775 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7776 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
7777 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
7778
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7779 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7780 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7781 (if (eq last-command 'kill-region)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7782 (kill-append string (< end beg))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7783 (kill-new string)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7784 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7785 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7786
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7787 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
7788 @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
7789
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7790 @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
7791 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
7792 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
7793
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7794 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7795 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
7796 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
7797
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7798 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7799 (kill-append string (< end beg))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7800 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7801
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7802 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7803 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
7804 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
7805 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
7806 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
7807 @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
7808
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7809 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
7810 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
7811 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
7812 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
7813 order is correct.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7814
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7815 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
7816 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
7817 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
7818 @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
7819
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7820 @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
7821 @comment node-name, next, previous, up
45663
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
7822 @section Digression into C
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7823 @findex delete-and-extract-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7824 @cindex C, a digression into
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7825 @cindex Digression into C
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 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
7828 @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
7829 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
7830 @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
7831 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
7832 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
7833 @code{copy-region-as-kill}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7834
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7835 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
7836 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
7837
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7838 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
7839 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
7840 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
7841 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
7842
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7843 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7844 Like many of the other Emacs primitives,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7845 @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
7846 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
7847 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7848
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7849 @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
7850 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7851 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7852 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
7853 Sdelete_and_extract_region, 2, 2, 0,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7854 "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
7855 (start, end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7856 Lisp_Object start, end;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7857 @{
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7858 validate_region (&start, &end);
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7859 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
7860 @}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7861 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7862 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7863
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7864 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
7865 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
7866 @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
7867 @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
7868 parts inside of parentheses:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7869
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7870 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7871 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7872 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
7873 @code{delete-and-extract-region}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7874
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7875 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7876 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
7877 @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
7878 @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
7879 instead.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7880
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7881 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7882 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
7883 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
7884 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
7885
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7886 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7887 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
7888 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
7889 arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7890
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7891 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7892 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
7893 @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
7894 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
7895 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
7896 (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
7897
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7898 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
7899 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
7900 @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
7901 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
7902 and provides a prompt.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7903
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7904 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7905 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
7906 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
7907 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
7908 return.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7909
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7910 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7911 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
7912 written like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7913
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7914 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7915 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7916 "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
7917 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
7918 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7919 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7920 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7921
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7922 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7923 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
7924 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
7925 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
7926 consists of the following two lines:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7927
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7928 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7929 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7930 validate_region (&start, &end);
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7931 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
7932 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7933 @end smallexample
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 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
7936 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
7937 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
7938 deletes the text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7939
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7940 @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
7941 updates the buffer and does other things.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7942
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7943 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
7944 @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
7945 (end)}}.
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 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
7948 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
7949 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
7950 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
7951 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
7952
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7953 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
7954 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
7955 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
7956 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
7957 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
7958
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7959 @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
7960 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
7961
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7962 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7963 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
7964
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7965 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7966 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
7967 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7970 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
7971 and the ending position, @code{end}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7972
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7973 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
7974 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
7975 all work.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7976
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7977 @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
7978 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7979 @section Initializing a Variable with @code{defvar}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7980 @findex defvar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7981 @cindex Initializing a variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7982 @cindex Variable initialization
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 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
7985 @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
7986 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
7987 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
7988 @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
7989 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
7990 form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7991
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7992 (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
7993 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
7994 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
7995
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7996 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
7997 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
7998 name comes from ``define variable''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7999
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8000 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
8001 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
8002 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
8003 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
8004 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
8005 documentation string.
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 (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
8008 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
8009 (@xref{defcustom, , Setting Variables with @code{defcustom}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8010
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8011 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8012 * See variable current value::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8013 * defvar and asterisk:: An old-time convention.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8014 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8015
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8016 @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
8017 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8018 @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
8019 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8020
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8021 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
8022 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
8023 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
8024 (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
8025 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
8026 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
8027 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
8028 @code{kill-ring}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8029
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8030 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8031 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8032 Documentation:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8033 List of killed text sequences.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8034 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
8035 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
8036 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8037 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8038 interact nicely with `interprogram-cut-function' and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8039 `interprogram-paste-function'. The functions `kill-new',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8040 `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
8041 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
8042 ring directly.
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 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8045
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8046 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8047 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
8048
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8049 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8050 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8051 (defvar kill-ring nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8052 "List of killed text sequences.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8053 @dots{}")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8054 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8055 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8056
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8057 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8058 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
8059 @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
8060 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
8061 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
8062 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
8063 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
8064 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
8065 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
8066 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
8067
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8068 @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
8069 @subsection @code{defvar} and an asterisk
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8070 @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
8071 @findex defvar @r{with an asterisk}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8072
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8073 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
8074 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
8075 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
8076 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
8077 @code{defcustom} instead, since that special form provides a path into
53099
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
8078 the Customization commands. (@xref{defcustom, , Specifying Variables
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
8079 using @code{defcustom}}.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8080
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8081 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
8082 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
8083 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
8084 string. For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8085
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8086 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8087 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8088 (defvar shell-command-default-error-buffer nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8089 "*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
8090 @dots{} ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8091 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8092 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8093
53099
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
8094 @findex set-variable
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
8095 @noindent
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
8096 You could (and still can) use the @code{set-variable} command to
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
8097 change the value of @code{shell-command-default-error-buffer}
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
8098 temporarily. However, options set using @code{set-variable} are set
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
8099 only for the duration of your editing session. The new values are not
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
8100 saved between sessions. Each time Emacs starts, it reads the original
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8101 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
8102 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
8103 @xref{Emacs Initialization, , Your @file{.emacs} File}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8104
53099
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
8105 For me, the major use of the @code{set-variable} command is to suggest
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
8106 variables that I might want to set in my @file{.emacs} file. There
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
8107 are now more than 700 such variables --- far too many to remember
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
8108 readily. Fortunately, you can press @key{TAB} after calling the
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
8109 @code{M-x set-variable} command to see the list of variables.
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
8110 (@xref{Examining, , Examining and Setting Variables, emacs,
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
8111 The GNU Emacs Manual}.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8112
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8113 @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
8114 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8115 @section @code{copy-region-as-kill}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8116 @findex copy-region-as-kill
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8117 @findex nthcdr
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 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
8120 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
8121 in the @code{kill-ring}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8122
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8123 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
8124 @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
8125 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
8126 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
8127 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
8128 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
8129
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8130 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8131 * 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
8132 * 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
8133 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8134
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8135 @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
8136 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8137 @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
8138 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8139
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8140 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8141 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
8142 function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8143
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
8144 @c !!! for no text properties, use buffer-substring-no-properties
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
8145
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8146 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8147 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8148 (defun copy-region-as-kill (beg end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8149 "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
8150 In Transient Mark mode, deactivate the mark.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8151 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
8152 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
8153 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8154 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8155 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8156 (if (eq last-command 'kill-region)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8157 (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
8158 (kill-new (buffer-substring beg end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8159 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8160 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8161 (if transient-mark-mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8162 (setq deactivate-mark t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8163 nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8164 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8165 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8166
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8167 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8168 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
8169
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8170 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8171 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8172 (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
8173 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8174 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8175 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8176 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8177 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8178
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8179 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
8180 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
8181 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
8182 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
8183 almost becoming routine.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8184
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8185 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
8186 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
8187 `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
8188 certain side-effects.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8189
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8190 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
8191 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
8192 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
8193 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
8194 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
8195 highlighted.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8196
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8197 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
8198 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
8199 @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
8200 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
8201 ring.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8202
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8203 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
8204 @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
8205 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
8206 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
8207 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
8208 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
8209 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
8210
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8211 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
8212 if Transient Mark mode is turned on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8213
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8214 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
8215
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8216 @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
8217 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8218 @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
8219
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8220 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
8221 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
8222 ,@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
8223 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
8224 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
8225 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
8226 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
8227 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
8228 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
8229
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8230 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
8231 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
8232 previous Emacs command.
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 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8235 * last-command & this-command::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8236 * kill-append function::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8237 * kill-new function::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8238 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8239
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8240 @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
8241 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8242 @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
8243 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8244
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8245 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
8246 @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
8247 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
8248 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
8249 @code{this-command}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8251 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
8252 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
8253 @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
8254 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
8255 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
8256 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
8257 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
8258 @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
8259 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
8260 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8261
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8262 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8263 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
8264 a function we have not yet seen:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8267 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8268 (if (eq last-command 'kill-region)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8269 ;; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8270 (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
8271 ;; @r{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8272 (kill-new (buffer-substring beg end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8273 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8274 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8275
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8276 @findex eq @r{(example of use)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8277 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8278 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
8279 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
8280 @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
8281 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
8282 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
8283 @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
8284 expressions are the same.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8285
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8286 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
8287 interpreter calls the @code{kill-append} function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8288
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8289 @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
8290 @unnumberedsubsubsec The @code{kill-append} function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8291 @findex kill-append
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8294 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
8295
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8296 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8297 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8298 (defun kill-append (string before-p)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8299 "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
8300 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
8301 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
8302 it."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8303 (kill-new (if before-p
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8304 (concat string (car kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8305 (concat (car kill-ring) string))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8306 t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8307 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8308 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8309
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8310 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8311 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
8312 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
8313 a moment.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8314
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8315 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
8316 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
8317 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
8318 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
8319
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8320 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8321 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8322 (if before-p ; @r{if-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8323 (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
8324 (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
8325 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8326 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8327
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8328 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8329 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
8330 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
8331 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
8332 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
8333 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
8334 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
8335 previously saved text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8336
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8337 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
8338 @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
8339 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
8340 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
8341 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
8342 this command is located before or after the kill text of the last
50621
0e3a9e34f995 Thanks to Hugo Gayosso, fix minor typos.
Robert J. Chassell <bob@rattlesnake.com>
parents: 47559
diff changeset
8343 command; what it does is determine whether the value of the variable
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8344 @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
8345 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
8346 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
8347 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
8348 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
8349 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
8350 @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
8351
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8352 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8353 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
8354 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
8355
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8356 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8357 (concat string (car kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8358 @end smallexample
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8361 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8362 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
8363 after the old text:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8364
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8365 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8366 (concat (car kill-ring) string))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8367 @end smallexample
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 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
8370 @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
8371 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
8372
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8373 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8374 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8375 (concat "abc" "def")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8376 @result{} "abcdef"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8377 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8378
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8379 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8380 (concat "new "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8381 (car '("first element" "second element")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8382 @result{} "new first element"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8383
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8384 (concat (car
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8385 '("first element" "second element")) " modified")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8386 @result{} "first element modified"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8387 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8388 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8389
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8390 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
8391 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
8392 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
8393 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
8394
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8395 @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
8396 @unnumberedsubsubsec The @code{kill-new} function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8397 @findex kill-new
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8400 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
8401
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8402 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8403 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8404 (defun kill-new (string &optional replace)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8405 "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
8406 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
8407 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
8408 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
8409 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
8410 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8411 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8412 (and (fboundp 'menu-bar-update-yank-menu)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8413 (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
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 (if (and replace kill-ring)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8417 (setcar kill-ring string)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8418 (setq kill-ring (cons string kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8419 (if (> (length kill-ring) kill-ring-max)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8420 (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
8421 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8422 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8423 (setq kill-ring-yank-pointer kill-ring)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8424 (if interprogram-cut-function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8425 (funcall interprogram-cut-function string (not replace))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8426 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8427 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8428
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8429 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
8430
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8431 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8432 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
8433
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8434 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8435 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
8436 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8439 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
8440
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8441 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
8442 @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
8443
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8444 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8445 The critical lines are these:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8446
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8447 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8448 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8449 (if (and replace kill-ring)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8450 ;; @r{then}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8451 (setcar kill-ring string)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8452 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8453 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8454 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8455 (setq kill-ring (cons string kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8456 (if (> (length kill-ring) kill-ring-max)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8457 ;; @r{avoid overly long kill ring}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8458 (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
8459 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8460 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8461 (setq kill-ring-yank-pointer kill-ring)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8462 (if interprogram-cut-function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8463 (funcall interprogram-cut-function string (not replace))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8464 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8465 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8466
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8467 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
8468 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
8469 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
8470
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8471 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8472 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
8473 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
8474 expression is executed:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8475
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8476 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8477 (setcar kill-ring string)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8478 @end smallexample
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 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
8481 @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
8482 first element.
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 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
8485 else-part of the condition is executed:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8486
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8487 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8488 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8489 (setq kill-ring (cons string kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8490 (if (> (length kill-ring) kill-ring-max)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8491 (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
8492 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8493 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8494
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8495 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8496 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
8497 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
8498 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
8499 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
8500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8501 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
8502
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8503 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
8504 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
8505 ring.
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8508 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
8509
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8510 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8511 (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
8512 @end smallexample
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8515 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8516 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
8517 @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
8518
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8519 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8520 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8521 example-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8522 @result{} ("here is a clause" "another clause")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8523 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8524 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8525
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8526 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8527 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8528 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
8529 following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8530 @findex cons, @r{example}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8531
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8532 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8533 (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
8534 @end smallexample
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8537 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8538 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
8539
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8540 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8541 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8542 example-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8543 @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
8544 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8545 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8546
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8547 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8548 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
8549
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8550 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8551 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
8552 the function. Here is the line again:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8555 (setq kill-ring (cons string kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8556 @end smallexample
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8559 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
8560 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
8561
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8562 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8563 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8564 (if (> (length kill-ring) kill-ring-max)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8565 (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
8566 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8567 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8568
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8569 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
8570 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
8571 @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
8572 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
8573 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
8574 @code{nthcdr} and @code{setcdr}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8575
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8576 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
8577 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
8578 @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
8579 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
8580 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
8581 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
8582 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
8583 the last element of the kill ring.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8584
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8585 @findex nthcdr, @r{example}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8586 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
8587 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
8588 @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
8589
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8590 @findex setcdr, @r{example}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8591 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
8592 elements long, we could set the @sc{cdr} of the next to last element
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
8593 to @code{nil}, and thereby shorten the list. (If you sent the last
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
8594 element to some other value than @code{nil}, which you could do, then
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
8595 you would not have shortened the list.)
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
8596
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
8597 You can see shortening by evaluating the following three expressions
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
8598 in turn. First set the value of @code{trees} to @code{(maple oak pine
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
8599 birch)}, then set the @sc{cdr} of its second @sc{cdr} to @code{nil}
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
8600 and then find the value of @code{trees}:
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8601
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8602 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8603 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8604 (setq trees '(maple oak pine birch))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8605 @result{} (maple oak pine birch)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8606 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8607
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8608 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8609 (setcdr (nthcdr 2 trees) nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8610 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8611
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8612 trees
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8613 @result{} (maple oak pine)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8614 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8615 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8616
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8617 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8618 (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
8619 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
8620
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8621 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
8622 @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
8623 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
8624 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
8625 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
8626
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8627 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8628 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
8629
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8630 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8631 (setq kill-ring-yank-pointer kill-ring)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8632 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8633
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8634 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
8635 the @code{kill-ring}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8636
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8637 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
8638 @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
8639 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
8640 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
8641 @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
8642
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8643 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8644 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
8645
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8646 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8647 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8648 (and (fboundp 'menu-bar-update-yank-menu)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8649 (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
8650 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8651 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8652
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8653 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8654 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
8655
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8656 @findex and, @r{introduced}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8657 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
8658 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
8659 @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
8660 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
8661 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
8662 @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
8663 @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
8664 are true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8665 @findex and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8666
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8667 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
8668 @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
8669 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
8670 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
8671 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
8672 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
8673 Errors, , Generate an Error Message}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8674
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8675 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8676 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
8677 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8678
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8679 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8680 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8681 if @var{the-menu-bar-function-exists}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8682 then @var{execute-it}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8683 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8684 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8685
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8686 @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
8687 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
8688 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
8689 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
8690
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8691 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
8692 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
8693 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
8694 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
8695 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
8696 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
8697
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8698 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8699 The expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8700
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8701 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8702 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8703 (if interprogram-cut-function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8704 (funcall interprogram-cut-function string (not replace))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8705 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8706 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8707
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8708 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
8709 @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
8710 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
8711 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
8712 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
8713
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8714 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
8715 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
8716 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
8717
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8718 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
8719 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
8720 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
8721 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
8722 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
8723 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
8724
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
8725 @need 1250
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8726 @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
8727 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8728 @section Review
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8729
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8730 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
8731
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8732 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8733 @item car
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8734 @itemx cdr
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8735 @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
8736 second and subsequent elements of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8737
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8738 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8739 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8740
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8741 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8742 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8743 (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
8744 @result{} 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8745 (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
8746 @result{} (2 3 4 5 6 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8747 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8748 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8749
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8750 @item cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8751 @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
8752 second argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8753
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8754 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8755 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8756
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8757 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8758 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8759 (cons 1 '(2 3 4))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8760 @result{} (1 2 3 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8761 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8762 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8763
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8764 @item nthcdr
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8765 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
8766 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8767 The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8768 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8769 $n^{th}$
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8770 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8771 @code{cdr}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8772 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8773 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
8774
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8775 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8776 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8777
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8778 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8779 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8780 (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
8781 @result{} (4 5 6 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8782 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8783 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8784
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8785 @item setcar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8786 @itemx setcdr
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8787 @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
8788 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
8789
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8790 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8791 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8792
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8793 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8794 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8795 (setq triple '(1 2 3))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8796
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8797 (setcar triple '37)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8798
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8799 triple
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8800 @result{} (37 2 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8801
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8802 (setcdr triple '("foo" "bar"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8803
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8804 triple
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8805 @result{} (37 "foo" "bar")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8806 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8807 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8808
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8809 @item progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8810 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
8811 last.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8812
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8813 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8814 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8815
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8816 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8817 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8818 (progn 1 2 3 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8819 @result{} 4
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8820 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8821 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8822
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8823 @item save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8824 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
8825 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
8826
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8827 @item search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8828 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
8829
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8830 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8831 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8832 Takes four arguments:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8833
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8834 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8835 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8836 The string to search for.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8837
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8838 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8839 Optionally, the limit of the search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8840
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8841 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8842 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
8843 error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8844
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8845 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8846 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
8847 search goes backwards.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8848 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8849
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8850 @item kill-region
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
8851 @itemx delete-and-extract-region
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8852 @itemx copy-region-as-kill
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8853
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8854 @code{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
8855 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
8856 by yanking.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8857
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8858 @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
8859 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
8860
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8861 @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
8862 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
8863 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
8864 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8865
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8866 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8867 @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
8868 @section Searching Exercises
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8869
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8870 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8871 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8872 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
8873 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
8874 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
8875 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
8876 @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
8877 @code{test-search} instead.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8878
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8879 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8880 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
8881 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
8882 print an appropriate message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8883 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8884
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8885 @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
8886 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8887 @chapter How Lists are Implemented
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8888 @cindex Lists in a computer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8889
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8890 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
8891 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
8892 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
8893 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
8894 @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
8895 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
8896 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
8897 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
8898 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
8899 @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
8900
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8901 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
8902 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
8903
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8904 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8905 * Lists diagrammed::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8906 * Symbols as Chest:: Exploring a powerful metaphor.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8907 * List Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8908 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8909
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8910 @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
8911 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8912 @unnumberedsec Lists diagrammed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8913 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8914
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8915 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
8916 @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
8917 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
8918 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
8919 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
8920 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
8921 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
8922
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8923 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8924 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
8925
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8926 @c clear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8927 @c !!! cons-cell-diagram #1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8928 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8929 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8930 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8931 ___ ___ ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8932 |___|___|--> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8933 | | |
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 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8936 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8937 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8938 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8939 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8940 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8941 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8942 @image{cons-1}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8943 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8944 % \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
8945 % \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
8946 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8947 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8948 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8949 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8950 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8951 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8952 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8953 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8954 ___ ___ ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8955 |___|___|--> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8956 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8957 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8958 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8959 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8960 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8961 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8962 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8963
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8964 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8965 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
8966 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
8967 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
8968 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
8969 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
8970 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
8971 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
8972 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
8973 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
8974
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8975 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8976 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
8977 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
8978 evaluation of the expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8979
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8980 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8981 (setq bouquet '(rose violet buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8982 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8983
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8984 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8985 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8986 creates a situation like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8987
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8988 @c cons-cell-diagram #2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8989 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8990 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8991 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8992 bouquet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8993 |
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 --> |___|___|--> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8996 | | |
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 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8999 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9000 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9001 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9002 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9003 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9004 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9005 @image{cons-2}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9006 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9007 % \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
9008 % \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
9009 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9010 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9011 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9012 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9013 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9014 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9015 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9016 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9017 bouquet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9018 |
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 --> |___|___|--> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9021 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9022 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9023 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9024 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9025 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9026 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9027 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9028
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9029 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9030 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
9031 pair of boxes.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9032
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9033 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9034 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
9035 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9036
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9037 @c cons-cell-diagram #2a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9038 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9039 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9040 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9041 bouquet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9042 |
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 | | car | cdr | | car | cdr | | car | cdr |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9045 -->| rose | o------->| violet | o------->| butter- | nil |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9046 | | | | | | | cup | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9047 -------------- --------------- ----------------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9048 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9049 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9050 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9051 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9052 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9053 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9054 @image{cons-2a}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9055 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9056 % \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
9057 % \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
9058 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9059 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9060 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9061 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9062 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9063 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9064 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9065 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9066 bouquet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9067 |
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 | | car | cdr | | car | cdr | | car | cdr |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9070 -->| rose | o------->| violet | o------->| butter- | nil |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9071 | | | | | | | cup | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9072 -------------- --------------- ----------------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9073 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9074 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9075 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9076 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9077
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9078 (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
9079 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
9080 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
9081 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
9082 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
9083 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
9084 @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
9085 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
9086 address-boxes for the list.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9087
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9088 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
9089 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
9090 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
9091 evaluation of the following expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9092
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9093 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9094 (setq flowers (cdr bouquet))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9095 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9096
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9097 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9098 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9099 produces this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9101 @c cons-cell-diagram #3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9102 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9103 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9104 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9105 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9106 bouquet flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9107 | |
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 |___|___|----> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9111 | | |
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 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9114 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9115 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9116 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9117 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9118 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9119 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9120 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9121 @image{cons-3}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9122 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9123 % \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
9124 % \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
9125 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9126 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9127 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9128 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9129 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9130 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9131 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9132 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9133 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9134 bouquet flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9135 | |
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 |___|___|----> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9139 | | |
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 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9142 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9143 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9144 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9145 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9146 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9147
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9148 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9149 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
9150 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
9151 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
9152 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
9153
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9154 A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted
53067
92487270aa3e On behalf of Kevin Ryde <user42@zip.com.au>: Corrections
Robert J. Chassell <bob@rattlesnake.com>
parents: 52401
diff changeset
9155 pair}. @xref{Cons Cell Type, , Cons Cell and List Types, elisp, The GNU Emacs Lisp
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9156 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
9157 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
9158 information about cons cells and dotted pairs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9159
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9160 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9161 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
9162 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
9163 the expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9164
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9165 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9166 (setq bouquet (cons 'lily bouquet))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9167 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9168
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9169 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9170 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9171 produces:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9172
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9173 @c cons-cell-diagram #4
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9174 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9175 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9176 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9177 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9178 bouquet flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9179 | |
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 |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9183 | | | |
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 --> lily --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9186 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9187 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9188 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9189 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9190 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9191 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9192 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9193 @image{cons-4}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9194 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9195 % \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
9196 % \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
9197 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9198 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9199 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9200 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9201 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9202 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9203 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9204 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9205 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9206 bouquet flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9207 | |
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 |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9211 | | | |
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 --> lily --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9214 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9215 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9216 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9217 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9218 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9219
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9220 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9221 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9222 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
9223 @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
9224
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9225 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9226 (eq (cdr (cdr bouquet)) flowers)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9227 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9228
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9229 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9230 which returns @code{t} for true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9231
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9232 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
9233 @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
9234 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
9235 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
9236
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9237 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
9238 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
9239 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
9240 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
9241 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
9242 brilliantly simple!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9243
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9244 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
9245 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
9246
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9247 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
9248 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
9249
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9250 @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
9251 @section Symbols as a Chest of Drawers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9252 @cindex 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 Chest of Drawers, metaphor for a symbol
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9254 @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
9255
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9256 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
9257 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
9258 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
9259 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
9260 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
9261
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9262 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
9263 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
9264 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
9265 where the buried treasure lies.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9266
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9267 (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
9268 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
9269 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
9270 @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
9271 Reference Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9272
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9273 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9274 Here is a fanciful representation:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9275
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9276 @c chest-of-drawers diagram
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9277 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9278 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9279 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9280 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9281 Chest of Drawers Contents of Drawers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9282
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9283 __ o0O0o __
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9284 / \
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 | directions to | [map to]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9287 | symbol name | bouquet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9288 | |
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 | directions to |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9291 | symbol definition | [none]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9292 | |
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 | directions to | [map to]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9295 | variable value | (rose violet buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9296 | |
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 | directions to |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9299 | property list | [not described here]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9300 | |
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 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9304 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9305 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9306 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9307 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9308 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9309 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9310 @image{drawers}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9311 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9312 % \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
9313 % \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
9314 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9315 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9316 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9317 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9318 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9319 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9320 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9321 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9322 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9323 Chest of Drawers Contents of Drawers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9324
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9325 __ o0O0o __
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9326 / \
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 | directions to | [map to]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9329 | symbol name | bouquet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9330 | |
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 | directions to |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9333 | symbol definition | [none]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9334 | |
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 | directions to | [map to]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9337 | variable value | (rose violet buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9338 | |
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 | directions to |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9341 | property list | [not described here]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9342 | |
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 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9346 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9347 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9348 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9349 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9350
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9351 @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
9352 @section Exercise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9353
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9354 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
9355 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
9356 @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
9357 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
9358
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9359 @node Yanking, Loops & Recursion, List Implementation, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9360 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9361 @chapter Yanking Text Back
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9362 @findex yank
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9363 @findex rotate-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9364 @cindex Text retrieval
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9365 @cindex Retrieving text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9366 @cindex Pasting text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9367
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9368 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
9369 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
9370 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
9371 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
9372 the original buffer).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9373
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9374 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
9375 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
9376 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
9377 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
9378 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
9379 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
9380 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
9381 `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
9382 that holds the text is a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9383 @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
9384 list is handled as a ring.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9385
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9386 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9387 * 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
9388 * 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
9389 * yank nthcdr Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9390 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9391
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9392 @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
9393 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9394 @section Kill Ring Overview
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9395 @cindex Kill ring overview
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9396
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9397 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
9398
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9399 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9400 ("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
9401 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9402
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9403 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
9404 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
9405 buffer where my cursor is located.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9406
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9407 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
9408 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
9409 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
9410
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9411 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
9412 @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
9413 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
9414 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
9415
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9416 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
9417 @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
9418 @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
9419
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9420 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9421 (insert (car kill-ring-yank-pointer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9422 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9423
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9424 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
9425 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
9426 and the @code{rotate-yank-pointer} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9427
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9428 @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
9429 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9430 @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
9431
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9432 @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
9433 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
9434 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
9435
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9436 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9437 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
9438
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9439 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9440 ("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
9441 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9442
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9443 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9444 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9445 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
9446 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
9447
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9448 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9449 ("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
9450 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9451
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9452 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
9453 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
9454 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
9455 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
9456 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
9457 text. Here is a diagram:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9458
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9459 @c cons-cell-diagram #5
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9460 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9461 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9462 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9463 kill-ring kill-ring-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9464 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9465 | ___ ___ | ___ ___ ___ ___
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 |___|___|----> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9468 | | |
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 | | --> "yet more text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9471 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9472 | --> "a different piece of text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9473 |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9474 --> "some text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9475 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9476 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9477 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9478 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9479 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9480 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9481 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9482 @image{cons-5}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9483 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9484 % \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
9485 % \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
9486 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9487 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9488 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9489 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9490 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9491 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9492 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9493 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9494 kill-ring kill-ring-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9495 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9496 | ___ ___ | ___ ___ ___ ___
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 |___|___|----> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9499 | | |
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 | | --> "yet more text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9502 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9503 | --> "a different piece of text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9504 |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9505 --> "some text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9506 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9507 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9508 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9509 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9510 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9511
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9512 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
9513 @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
9514 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
9515 @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
9516 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
9517 spoken of as pointing to a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9518
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9519 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
9520 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
9521 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
9522 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
9523 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
9524 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
9525 inserted.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9526
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9527 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
9528 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
9529 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
9530 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
9531 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
9532 @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
9533 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
9534 @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
9535 @xref{Kill Ring, , Handling the Kill Ring}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9536
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9537 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9538 @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
9539 @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
9540
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9541 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9542 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9543 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
9544 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
9545 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
9546 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
9547 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
9548 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
9549
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9550 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9551 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
9552 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
9553 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9554
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9555 @node Loops & Recursion, Regexp Search, Yanking, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9556 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9557 @chapter Loops and Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9558 @cindex Loops and recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9559 @cindex Recursion and loops
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9560 @cindex Repetition (loops)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9561
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9562 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
9563 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
9564 loop, and the other uses @dfn{recursion}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9565
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9566 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
9567 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
9568 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
9569 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
9570 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
9571 have on humans.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9572
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9573 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
9574 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
9575 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
9576 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
9577 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
9578 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
9579 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
9580 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
9581 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
9582 @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
9583 15 and 30 times their default value.}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9584
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9585 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9586 * 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
9587 * dolist dotimes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9588 * Recursion:: Causing a function to call itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9589 * Looping exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9590 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9591
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9592 @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
9593 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9594 @section @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9595 @cindex Loops
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9596 @findex while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9597
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9598 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
9599 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
9600 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
9601 next, however, is different.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9602
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9603 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
9604 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
9605 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
9606 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
9607 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
9608 @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
9609 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
9610 body of the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9611
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9612 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9613 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
9614
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9615 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9616 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9617 (while @var{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9618 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9619 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9620 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9621
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9622 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9623 * 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
9624 * 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
9625 * 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
9626 * 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
9627 * 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
9628 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9629
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9630 @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
9631 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9632 @unnumberedsubsec Looping with @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9633 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9634
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9635 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
9636 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
9637 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
9638 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
9639 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
9640 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
9641 expression and `exits the loop'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9642
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9643 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
9644 @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
9645 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
9646 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
9647 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
9648 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
9649 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
9650 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
9651
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9652 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
9653 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
9654 @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
9655 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
9656 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
9657 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
9658 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
9659 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
9660 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
9661 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
9662 are repeatedly evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9663
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9664 @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
9665 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9666 @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
9667
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9668 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
9669 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
9670 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
9671 create a short example to illustrate it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9672
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9673 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
9674 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
9675 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
9676 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
9677 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
9678 @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
9679 @code{while} loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9680
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9681 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9682 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
9683 evaluating the following @code{setq} expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9684
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9685 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9686 (setq empty-list ())
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9687 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9688
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9689 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9690 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
9691 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
9692 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
9693 echo area:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9694
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9695 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9696 empty-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9697 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9698
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9699 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
9700 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
9701 evaluating the following two expressions:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9702
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9703 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9704 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9705 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9706
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9707 animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9708 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9709 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9710
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9711 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
9712 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
9713 written like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9714
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9715 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9716 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9717 (while animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9718 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9719 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9720 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9721
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9722 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9723 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
9724 @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
9725 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
9726 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
9727 to be false.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9728
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9729 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
9730 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
9731 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
9732 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
9733 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
9734 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
9735 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
9736 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
9737
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9738 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
9739 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
9740 following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9741
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9742 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9743 (setq animals (cdr animals))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9744 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9745
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9746 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9747 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
9748 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
9749 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
9750 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
9751 @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
9752
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9753 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
9754 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
9755 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9756
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9757 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9758 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9759 (while @var{test-whether-list-is-empty}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9760 @var{body}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9761 @var{set-list-to-cdr-of-list})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9762 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9763 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9764
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9765 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
9766 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
9767 own.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9768
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9769 @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
9770 @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
9771 @findex print-elements-of-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9772
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9773 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
9774 loop with a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9775
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9776 @cindex @file{*scratch*} buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9777 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
9778 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
9779 following expression inside of Info, as usual.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9780
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9781 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
9782 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
9783 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
9784 earlier versions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9785
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9786 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
9787 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
9788 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
9789 (@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
9790 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
9791
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9792 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
9793 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
9794 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
9795 @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
9796 @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
9797 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
9798 in the echo area. (Otherwise you will see something like this in your
45663
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
9799 echo area: @code{^Jgazelle^J^Jgiraffe^J^Jlion^J^Jtiger^Jnil}, in which
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9800 each @samp{^J} stands for a `newline'.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9801
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9802 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9803 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
9804 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
9805 results.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9806
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9807 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9808 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9809 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9810
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9811 (defun print-elements-of-list (list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9812 "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
9813 (while list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9814 (print (car list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9815 (setq list (cdr list))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9816
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9817 (print-elements-of-list animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9818 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9819 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9820
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9821 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9822 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9823 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
9824 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9825
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9826 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9827 @group
45663
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
9828 gazelle
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
9829
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9830 giraffe
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9831
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9832 lion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9833
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9834 tiger
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9835 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9836 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9837 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9838
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9839 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
9840 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
9841 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
9842 @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
9843 @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
9844
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9845 @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
9846 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9847 @subsection A Loop with an Incrementing Counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9848
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9849 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
9850 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
9851 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
9852 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
9853 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
9854 repeats itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9855
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9856 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
9857 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
9858 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
9859 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
9860 @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
9861 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
9862 @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
9863 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
9864 @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
9865
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9866 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9867 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
9868 counter looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9869
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9870 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9871 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9872 @var{set-count-to-initial-value}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9873 (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
9874 @var{body}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9875 (setq count (1+ count))) ; @r{incrementer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9876 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9877 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9878
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9879 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9880 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
9881 is set to 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9882
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9883 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9884 * Incrementing Example:: Counting pebbles in a triangle.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9885 * 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
9886 * 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
9887 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9888
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9889 @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
9890 @unnumberedsubsubsec Example with incrementing counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9891
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9892 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
9893 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
9894 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
9895
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9896 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9897 @c pebble diagram
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9898 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9899 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9900 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9901 *
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 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9906 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9907 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9908 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9909 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9910 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9911 @bullet{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9912 @bullet{} @bullet{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9913 @bullet{} @bullet{} @bullet{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9914 @bullet{} @bullet{} @bullet{} @bullet{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9915 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9916 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9917 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9918 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9919
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9920 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9921 (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
9922 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
9923
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9924 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
9925 triangle with 7 rows?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9926
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9927 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
9928 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
9929 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
9930 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
9931 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
9932 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
9933 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
9934
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9935 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
9936 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
9937 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
9938 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
9939 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
9940 a more complex process once.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9941
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9942 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
9943 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
9944 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
9945 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
9946 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
9947
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9948 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
9949 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
9950 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
9951 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
9952 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
9953 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
9954 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
9955
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9956 @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
9957 @unnumberedsubsubsec The parts of the function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9958
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9959 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
9960 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
9961 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
9962 the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9963
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9964 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
9965 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
9966 called @code{number-of-rows}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9967
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9968 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
9969 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
9970 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
9971 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
9972
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9973 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
9974 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
9975 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
9976 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
9977 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
9978 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
9979 more rows left to add.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9980
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9981 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
9982 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
9983 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
9984 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
9985 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
9986 statement will look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9987
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9988 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9989 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9990 (let ((total 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9991 (row-number 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9992 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9993 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9994 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9995
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9996 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
9997 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
9998 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
9999 @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
10000 (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
10001 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
10002 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
10003 equal to the number of rows.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10004
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10005 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10006 @findex <= @r{(less than or equal)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10007 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
10008 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
10009 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
10010 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
10011
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10012 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10013 (<= row-number number-of-rows)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10014 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10015
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10016 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
10017 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
10018 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
10019 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
10020 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
10021 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
10022 would be replaced by the appropriate expression.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10023
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10024 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10025 (setq total (+ total row-number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10026 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10027
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10028 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10029 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
10030 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
10031
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10032 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
10033 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
10034 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
10035 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
10036 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
10037 @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
10038 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
10039 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
10040 repetition of the loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10041
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10042 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10043 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
10044 @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
10045
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10046 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10047 (setq row-number (1+ row-number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10048 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10049
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10050 @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
10051 @unnumberedsubsubsec Putting the function definition together
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10052
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10053 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
10054 put them together.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10055
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10056 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10057 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
10058
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10059 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10060 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10061 (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
10062 (setq total (+ total row-number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10063 (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
10064 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10065 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10066
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10067 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
10068 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
10069 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
10070
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10071 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
10072 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
10073 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
10074 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
10075 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
10076
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10077 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
10078 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
10079 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
10080 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
10081 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
10082 of the @code{let}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10083
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10084 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10085 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
10086
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10087 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10088 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10089 (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
10090 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10091 (let (@var{varlist})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10092 (while (@var{true-or-false-test})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10093 @var{body-of-while}@dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10094 @dots{} ) ; @r{Need final expression here.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10095 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10096 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10097
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10098 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
10099 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
10100 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
10101 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
10102 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
10103 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
10104 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
10105 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
10106 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
10107 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
10108
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10109 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
10110 @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
10111 @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
10112 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
10113 the last element:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10114
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10115 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10116 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10117 (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
10118 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10119 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10120
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10121 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10122 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
10123 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10124
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10125 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10126 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10127 (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
10128 ; @r{ incrementing counter.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10129 "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
10130 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
10131 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
10132 The argument is NUMBER-OF-ROWS."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10133 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10134 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10135 (let ((total 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10136 (row-number 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10137 (while (<= row-number number-of-rows)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10138 (setq total (+ total row-number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10139 (setq row-number (1+ row-number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10140 total))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10141 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10142 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10143
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10144 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10145 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
10146 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
10147
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10148 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10149 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10150 (triangle 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10151
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10152 (triangle 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10153 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10154 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10155
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10156 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10157 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
10158 numbers is 28.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10159
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10160 @node Decrementing Loop, , Incrementing Loop, while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10161 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10162 @subsection Loop with a Decrementing Counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10163
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10164 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
10165 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
10166 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
10167 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
10168 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
10169 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
10170 repeatedly.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10171
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10172 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
10173 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
10174 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
10175 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
10176 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
10177 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
10178 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
10179
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10180 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10181 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
10182
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10183 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10184 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10185 (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
10186 @var{body}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10187 (setq counter (1- counter))) ; @r{decrementer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10188 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10189 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10190
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10191 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10192 * Decrementing Example:: More pebbles on the beach.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10193 * 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
10194 * 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
10195 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10196
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10197 @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
10198 @unnumberedsubsubsec Example with decrementing counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10199
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10200 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
10201 @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
10202
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10203 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
10204 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
10205 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
10206 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
10207 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
10208
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10209 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
10210 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
10211 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
10212 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
10213 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
10214 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
10215 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
10216 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
10217
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10218 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
10219 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
10220 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
10221 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
10222 the row.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10223
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10224 @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
10225 @unnumberedsubsubsec The parts of the function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10226
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10227 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
10228 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
10229 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
10230 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
10231 @code{total}, respectively.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10232
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10233 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
10234 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
10235 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
10236 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
10237 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
10238 the longest row.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10239
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10240 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10241 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
10242 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10243
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10244 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10245 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10246 (let ((total 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10247 (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
10248 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10249 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10250 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10251
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10252 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
10253 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
10254 evaluating the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10255
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10256 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10257 (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
10258 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10259
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10260 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10261 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
10262 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
10263 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
10264 added to the total.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10265
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10266 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
10267 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
10268 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
10269 done with the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10270
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10271 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10272 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10273 (setq number-of-pebbles-in-row
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10274 (1- number-of-pebbles-in-row))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10275 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10276 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10277
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10278 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
10279 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
10280 the @code{while} loop is simply:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10281
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10282 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10283 (while (> number-of-pebbles-in-row 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10284 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10285
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10286 @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
10287 @unnumberedsubsubsec Putting the function definition together
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10288
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10289 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
10290 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
10291 variables is unneeded!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10292
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10293 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10294 The function definition looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10295
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10296 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10297 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10298 ;;; @r{First subtractive version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10299 (defun triangle (number-of-rows)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10300 "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
10301 (let ((total 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10302 (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
10303 (while (> number-of-pebbles-in-row 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10304 (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
10305 (setq number-of-pebbles-in-row
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10306 (1- number-of-pebbles-in-row)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10307 total))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10308 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10309 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10310
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10311 As written, this function works.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10312
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10313 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
10314
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10315 @cindex Argument as local variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10316 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
10317 @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
10318 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
10319 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
10320 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
10321 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
10322 @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
10323 @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
10324
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10325 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10326 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
10327
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10328 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10329 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10330 (defun triangle (number) ; @r{Second version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10331 "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
10332 (let ((total 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10333 (while (> number 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10334 (setq total (+ total number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10335 (setq number (1- number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10336 total))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10337 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10338 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10339
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10340 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
10341
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10342 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10343 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10344 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
10345 correct number of times.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10346
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10347 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10348 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
10349 after being repeatedly evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10350
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10351 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10352 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
10353 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
10354 number of times.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10355 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10356
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10357 @node dolist dotimes, Recursion, while, Loops & Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10358 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10359 @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
10360
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10361 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
10362 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
10363 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
10364 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
10365
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10366 @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
10367 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
10368 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
10369 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
10370
44899
ebddb2618c17 Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 43431
diff changeset
10371 @code{dotimes} loops a specific number of times: you specify the number.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10372
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10373 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10374 * dolist::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10375 * dotimes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10376 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10377
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10378 @node dolist, dotimes, dolist dotimes, dolist dotimes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10379 @unnumberedsubsubsec The @code{dolist} Macro
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10380 @findex dolist
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10381
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10382 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
10383 ``first'' ``second'' ``third'' becomes ``third'' ``second'' ``first''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10384
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10385 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10386 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
10387
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10388 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10389 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10390 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10391
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10392 (reverse animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10393 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10394 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10395
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10396 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10397 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10398 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
10399
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10400 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10401 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10402 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10403
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10404 (defun reverse-list-with-while (list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10405 "Using while, reverse the order of LIST."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10406 (let (value) ; make sure list starts empty
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10407 (while list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10408 (setq value (cons (car list) value))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10409 (setq list (cdr list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10410 value))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10411
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10412 (reverse-list-with-while animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10413 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10414 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10415
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10416 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10417 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10418 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
10419
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10420 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10421 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10422 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10423
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10424 (defun reverse-list-with-dolist (list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10425 "Using dolist, reverse the order of LIST."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10426 (let (value) ; make sure list starts empty
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10427 (dolist (element list value)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10428 (setq value (cons element value)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10429
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10430 (reverse-list-with-dolist animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10431 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10432 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10433
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10434 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10435 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10436 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
10437 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
10438
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10439 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10440 (tiger lion giraffe gazelle)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10441 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10442
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10443 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10444 in the echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10445
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10446 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
10447 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
10448 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
10449 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
10450 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
10451 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
10452 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
10453 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
10454
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10455 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
10456 the @w{@code{(setq list (cdr list))}}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10457 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
10458 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
10459 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
10460 the loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10461
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10462 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
10463 @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
10464 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
10465
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10466 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
10467 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
10468 `@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
10469 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
10470 arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10471
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10472 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
10473 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
10474 @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
10475 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
10476
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10477 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
10478 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
10479 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
10480 @code{value}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10481
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10482 @node dotimes, , dolist, dolist dotimes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10483 @unnumberedsubsubsec The @code{dotimes} Macro
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10484 @findex dotimes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10485
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10486 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
10487 loops a specific number of times.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10488
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10489 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
10490 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
10491 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
10492 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
10493
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10494 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10495 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
10496 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
10497 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
10498 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
10499 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
10500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10501 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10502 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10503 (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
10504 (dotimes (number 3 value)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10505 (setq value (cons number value))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10506
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10507 @result{} (2 1 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10508 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10509 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10510
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10511 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10512 @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
10513 @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
10514 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
10515
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10516 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10517 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
10518 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
10519
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10520 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10521 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10522 (defun triangle-using-dotimes (number-of-rows)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10523 "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
10524 (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
10525 (dotimes (number number-of-rows total)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10526 (setq total (+ total (1+ number))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10527
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10528 (triangle-using-dotimes 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10529 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10530 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10531
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10532 @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
10533 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10534 @section Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10535 @cindex Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10536
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10537 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
10538 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
10539 different arguments. The code runs exactly the same because it has
45663
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
10540 the same name. However, even though the program has the same name, it
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
10541 is not the same entity. It is different. In the jargon, it is a
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
10542 different `instance'.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10543
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10544 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
10545 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
10546 arguments that the final instance will stop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10547
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10548 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10549 * Building Robots:: Same model, different serial number ...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10550 * Recursive Definition Parts:: Walk until you stop ...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10551 * 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
10552 * Recursive triangle function::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10553 * Recursion with cond::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10554 * Recursive Patterns:: Often used templates.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10555 * No Deferment:: Don't store up work ...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10556 * No deferment solution::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10557 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10558
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10559 @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
10560 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10561 @subsection Building Robots: Extending the Metaphor
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10562 @cindex Building robots
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10563 @cindex Robots, building
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10564
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10565 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
10566 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
10567 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
10568 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
10569 passed different arguments than the first.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10570
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10571 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
10572 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
10573 entity; but all are clones.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10574
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10575 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
10576 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
10577 when to stop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10578
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10579 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
10580
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10581 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
10582 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
10583 @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
10584 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
10585 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
10586 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
10587 but a different `serial number'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10588
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10589 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
10590 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
10591 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
10592 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
10593
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10594 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
10595 next; otherwise, the process will never stop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10596
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10597 @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
10598 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10599 @subsection The Parts of a Recursive Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10600 @cindex Parts of a Recursive Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10601 @cindex Recursive Definition Parts
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10602
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10603 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
10604 has three parts:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10605
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10606 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10607 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10608 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
10609 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
10610
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10611 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10612 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
10613 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
10614
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10615 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10616 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
10617 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
10618 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
10619 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
10620 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
10621 false after the correct number of repetitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10622 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10623
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10624 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
10625 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
10626 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
10627 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
10628 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
10629
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10630 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10631 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
10632 pattern looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10633
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10634 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10635 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10636 (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
10637 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10638 (if @var{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10639 @var{body}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10640 (@var{name-of-recursive-function}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10641 @var{next-step-expression})))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10642 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10643 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10644
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10645 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
10646 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
10647
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10648 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
10649 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
10650
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10651 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
10652
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10653 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
10654 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
10655 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
10656 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
10657 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
10658
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10659 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
10660 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
10661
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10662 @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
10663 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10664 @subsection Recursion with a List
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10665
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10666 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
10667 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
10668 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
10669
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10670 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
10671 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
10672 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
10673 @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
10674 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
10675 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
10676
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10677 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
10678 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
10679 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
10680
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10681 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
10682 directly in Info.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10683
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10684 @findex print-elements-recursively
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10685 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10686 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10687 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10688
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10689 (defun print-elements-recursively (list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10690 "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
10691 Uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10692 (if list ; @r{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10693 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10694 (print (car list)) ; @r{body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10695 (print-elements-recursively ; @r{recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10696 (cdr list))))) ; @r{next-step-expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10697
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10698 (print-elements-recursively animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10699 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10700 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10701
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10702 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
10703 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
10704 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
10705 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
10706 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
10707 @sc{cdr} of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10708
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10709 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
10710 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
10711 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
10712 instance.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10713
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10714 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
10715 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
10716 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
10717
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10718 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
10719 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
10720 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
10721 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
10722 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
10723 the @sc{cdr} of the original list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10724
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10725 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
10726 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
10727 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
10728 but is a separate individual.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10729
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10730 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
10731 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
10732 works on a shorter list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10733
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10734 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
10735 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
10736 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
10737 @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
10738 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
10739
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10740 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10741 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
10742 @file{*scratch*} buffer, you see this result:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10743
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10744 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10745 @group
45663
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
10746 gazelle
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
10747
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10748 giraffe
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10749
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10750 lion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10751
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10752 tiger
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10753 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10754 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10755 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10756
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10757 @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
10758 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10759 @subsection Recursion in Place of a Counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10760 @findex triangle-recursively
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10761
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10762 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10763 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
10764 be written recursively. It looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10765
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10766 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10767 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10768 (defun triangle-recursively (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10769 "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
10770 Uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10771 (if (= number 1) ; @r{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10772 1 ; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10773 (+ number ; @r{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10774 (triangle-recursively ; @r{recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10775 (1- number))))) ; @r{next-step-expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10776
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10777 (triangle-recursively 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10778 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10779 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10780
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10781 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10782 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
10783 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
10784 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
10785 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
10786
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10787 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
10788 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
10789 its argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10790
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10791 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10792 * Recursive Example arg of 1 or 2::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10793 * Recursive Example arg of 3 or 4::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10794 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10795
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10796 @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
10797 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10798 @unnumberedsubsubsec An argument of 1 or 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10799 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10801 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
10802
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10803 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
10804 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
10805 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
10806 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
10807 one row has one pebble in it.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10808
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10809 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
10810 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
10811
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10812 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10813 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
10814 @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
10815 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10816
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10817 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10818 (+ number (triangle-recursively (1- number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10819 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10820
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10821 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
10822 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
10823 in detail:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10824
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10825 @table @i
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10826 @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
10827
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10828 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
10829 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
10830
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10831 @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
10832
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10833 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
10834 @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
10835 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
10836 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
10837 function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10838
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10839 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
10840 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
10841 @code{triangle-recursively} returns 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10842
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10843 @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
10844
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10845 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
10846 starts with @code{+}; its value is 2.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10847
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10848 @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
10849
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10850 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
10851 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
10852 evaluation of @code{triangle-recursively} (Step 2).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10853
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10854 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
10855 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
10856 pebbles in it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10857 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10858
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10859 @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
10860 @unnumberedsubsubsec An argument of 3 or 4
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10861
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10862 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
10863 3.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10864
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10865 @table @i
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10866 @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
10867
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10868 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
10869 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
10870 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
10871 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
10872 true.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10873
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10874 @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
10875
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10876 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
10877 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
10878
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10879 @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
10880
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10881 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
10882
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10883 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
10884 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
10885 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
10886
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10887 @item Step 4 @w{ } Evaluate the addition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10888
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10889 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
10890 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
10891 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10892
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10893 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10894 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
10895
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10896 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
10897 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
10898 called with an argument of 4:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10899
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10900 @quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10901 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10902 In the recursive call, the evaluation of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10903
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10904 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10905 (triangle-recursively (1- 4))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10906 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10907
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10908 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10909 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10910 will return the value of evaluating
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10911
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10912 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10913 (triangle-recursively 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10914 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10915
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10916 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10917 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
10918 third line.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10919 @end quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10920
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10921 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10922 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
10923
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10924 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
10925 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
10926 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
10927 evaluate itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10928
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10929 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
10930 requires that operations be deferred.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10931
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10932 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
10933 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
10934 @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
10935 @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
10936 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
10937 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
10938 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
10939 @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
10940
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10941 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
10942 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
10943 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
10944 on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10945
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10946 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
10947 @ref{No Deferment, , Recursion without Deferments}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10948
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10949 @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
10950 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10951 @subsection Recursion Example Using @code{cond}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10952 @findex cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10953
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10954 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
10955 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
10956 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
10957 @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
10958
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10959 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
10960 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
10961 explaining it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10962
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10963 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10964 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
10965
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10966 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10967 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10968 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10969 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10970 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10971 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10972
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10973 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10974 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
10975
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10976 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10977 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
10978
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10979 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10980 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10981 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10982 (@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
10983 (@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
10984 (@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
10985 @dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10986 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10987 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10988
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10989 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
10990 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
10991 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
10992 @code{cond}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10993
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10994 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
10995 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
10996 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
10997 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
10998 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
10999 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
11000 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
11001 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
11002 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
11003
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11004 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
11005 returns @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11006
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11007 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11008 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
11009
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11010 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11011 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11012 (defun triangle-using-cond (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11013 (cond ((<= number 0) 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11014 ((= number 1) 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11015 ((> number 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11016 (+ number (triangle-using-cond (1- number))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11017 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11018 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11019
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11020 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11021 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
11022 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
11023 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
11024 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11025
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11026 @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
11027 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11028 @subsection Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11029 @cindex Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11030
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11031 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
11032 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
11033 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
11034
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11035 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11036 * Every::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11037 * Accumulate::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11038 * Keep::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11039 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11040
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11041 @node Every, Accumulate, Recursive Patterns, Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11042 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11043 @unnumberedsubsubsec Recursive Pattern: @emph{every}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11044 @cindex Every, type of recursive pattern
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11045 @cindex Recursive pattern: every
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11046
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11047 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
11048 element of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11049
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11050 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11051 The basic pattern is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11052
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11053 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11054 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11055 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
11056 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11057 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
11058 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11059 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11060 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
11061 @sc{cdr}) of the list,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11062 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11063 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
11064 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
11065 @end itemize
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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11068 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11069 Here is example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11070
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11071 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11072 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11073 (defun square-each (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11074 "Square each of a NUMBERS LIST, recursively."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11075 (if (not numbers-list) ; do-again-test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11076 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11077 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11078 (* (car numbers-list) (car numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11079 (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
11080 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11081
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11082 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11083 (square-each '(1 2 3))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11084 @result{} (1 4 9)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11085 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11086 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11087
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11088 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11089 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11090 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
11091 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
11092 with the result of the recursive call.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11093
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11094 (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
11095 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
11096 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
11097 empty.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11098
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11099 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
11100 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
11101 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
11102 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
11103
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11104 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11105 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
11106
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11107 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11108 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11109 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11110 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11111
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11112 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11113 (defun print-elements-recursively (list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11114 "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
11115 Uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11116 (if list ; @r{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11117 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11118 (print (car list)) ; @r{body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11119 (print-elements-recursively ; @r{recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11120 (cdr list))))) ; @r{next-step-expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11121
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11122 (print-elements-recursively animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11123 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11124 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11125
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11126 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11127 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
11128
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11129 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11130 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11131 If the list be empty, do nothing.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11132 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11133 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
11134 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11135 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11136 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
11137 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11138 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
11139 @end itemize
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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11142 @node Accumulate, Keep, Every, Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11143 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11144 @unnumberedsubsubsec Recursive Pattern: @emph{accumulate}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11145 @cindex Accumulate, type of recursive pattern
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11146 @cindex Recursive pattern: accumulate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11147
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11148 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
11149 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
11150 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
11151 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
11152
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11153 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
11154 @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
11155
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11156 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11157 The pattern is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11158
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11159 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11160 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11161 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
11162 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11163 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
11164 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11165 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11166 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
11167 some other combining function, with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11168 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11169 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
11170 @end itemize
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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11173 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11174 Here is an example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11175
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11176 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11177 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11178 (defun add-elements (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11179 "Add the elements of NUMBERS-LIST together."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11180 (if (not numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11181 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11182 (+ (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
11183 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11184
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11185 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11186 (add-elements '(1 2 3 4))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11187 @result{} 10
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11188 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11189 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11190
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11191 @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
11192 accumulate pattern.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11193
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11194 @node Keep, , Accumulate, Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11195 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11196 @unnumberedsubsubsec Recursive Pattern: @emph{keep}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11197 @cindex Keep, type of recursive pattern
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11198 @cindex Recursive pattern: keep
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11199
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11200 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
11201 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
11202 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
11203 meets a criterion.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11204
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11205 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
11206 skipped unless it meets a criterion.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11207
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11208 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11209 The pattern has three parts:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11210
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11211 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11212 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11213 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
11214 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11215 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
11216 a test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11217 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11218 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11219 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
11220 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11221 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
11222 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11223 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11224 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
11225 the test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11226 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11227 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11228 skip on that element,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11229 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11230 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
11231 @end itemize
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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11234 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11235 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
11236
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11237 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11238 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11239 (defun keep-three-letter-words (word-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11240 "Keep three letter words in WORD-LIST."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11241 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11242 ;; First do-again-test: stop-condition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11243 ((not word-list) nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11244
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11245 ;; Second do-again-test: when to act
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11246 ((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
11247 ;; 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
11248 (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
11249
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11250 ;; 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
11251 ;; 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
11252 (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
11253 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11254
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11255 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11256 (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
11257 @result{} (one two six)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11258 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11259 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11260
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11261 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
11262 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
11263
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11264 @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
11265 @subsection Recursion without Deferments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11266 @cindex Deferment in recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11267 @cindex Recursion without Deferments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11268
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11269 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
11270 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
11271 deferred until all can be done.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11272
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11273 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11274 Here is the function definition:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11275
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11276 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11277 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11278 (defun triangle-recursively (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11279 "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
11280 Uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11281 (if (= number 1) ; @r{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11282 1 ; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11283 (+ number ; @r{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11284 (triangle-recursively ; @r{recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11285 (1- number))))) ; @r{next-step-expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11286 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11287 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11288
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11289 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
11290
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11291 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
11292 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
11293 @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
11294 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
11295
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11296 @smallexample
45663
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
11297 (+ 7 (triangle-recursively 6))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11298 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11299
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11300 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11301 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
11302 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
11303 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
11304 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
11305 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
11306 `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
11307 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
11308 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
11309
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11310 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
11311 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
11312 @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
11313 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
11314
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11315 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11316 Now the total is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11317
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11318 @smallexample
45663
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
11319 (+ 7 6 (triangle-recursively 5))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11320 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11321
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11322 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11323 And what happens next?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11324
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11325 @smallexample
45663
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
11326 (+ 7 6 5 (triangle-recursively 4))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11327 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11328
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11329 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
11330 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
11331 asks it to make a calculation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11332
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11333 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11334 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
11335
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11336 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11337 (+ 7 6 5 4 3 2 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11338 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11339
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11340 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
11341 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
11342 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
11343 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
11344 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
11345 more steps.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11346
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11347 @node No deferment solution, , No Deferment, Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11348 @subsection No Deferment Solution
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11349 @cindex No deferment solution
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11350 @cindex Defermentless solution
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11351 @cindex Solution without deferment
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11352
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11353 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
11354 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
11355 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
11356 `constant space'.}. This requires
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11357 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
11358 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
11359 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11360
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11361 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
11362 does the work.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11363
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11364 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11365 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
11366 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
11367
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11368 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11369 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11370 (defun triangle-initialization (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11371 "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
11372 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
11373 duo that uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11374 (triangle-recursive-helper 0 0 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11375 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11376 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11377
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11378 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11379 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11380 (defun triangle-recursive-helper (sum counter number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11381 "Return SUM, using COUNTER, through NUMBER inclusive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11382 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
11383 that uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11384 (if (> counter number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11385 sum
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11386 (triangle-recursive-helper (+ sum counter) ; @r{sum}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11387 (1+ counter) ; @r{counter}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11388 number))) ; @r{number}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11389 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11390 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11391
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11392 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11393 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
11394 @code{triangle-initialization} with 2 rows:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11395
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11396 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11397 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11398 (triangle-initialization 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11399 @result{} 3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11400 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11401 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11402
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11403 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
11404 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
11405 number of rows in the triangle.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11406
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11407 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
11408 initialization values. These values are changed when
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11409 @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
11410 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
11411 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
11412 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
11413 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
11414 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
11415 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
11416 @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
11417 `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
11418
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11419 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
11420 triangle will have one pebble in it!)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11422 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11423 @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
11424 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
11425 test whether @code{(> counter number)}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11426
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11427 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11428 (> 0 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11429 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11430
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11431 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11432 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11433 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
11434 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
11435
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11436 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11437 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11438 (triangle-recursive-helper
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11439 (+ 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
11440 (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
11441 number) ; @r{number stays the same}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11442 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11443 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11444
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11445 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11446 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11447 which will first compute:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11448
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11449 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11450 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11451 (triangle-recursive-helper (+ 0 0) ; @r{sum}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11452 (1+ 0) ; @r{counter}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11453 1) ; @r{number}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11454 @exdent which is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11455
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11456 (triangle-recursive-helper 0 1 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11457 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11458 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11459
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11460 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
11461 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
11462 new instance with new arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11463
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11464 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11465 This new instance will be;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11466
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11467 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11468 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11469 (triangle-recursive-helper
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11470 (+ 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
11471 (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
11472 number) ; @r{number stays the same}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11473
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11474 @exdent which is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11475
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11476 (triangle-recursive-helper 1 2 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11477 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11478 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11479
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11480 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
11481 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
11482 expected.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11483
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11484 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
11485 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
11486
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11487 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
11488
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11489 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11490 In stages, the instances called will be:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11491
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11492 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11493 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11494 @r{sum counter number}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11495 (triangle-recursive-helper 0 1 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11496
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11497 (triangle-recursive-helper 1 2 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11498
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11499 (triangle-recursive-helper 3 3 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11500 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11501 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11502
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11503 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
11504 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
11505 which will be 3.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11506
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11507 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
11508 many resources in a computer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11509
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11510 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11511 @node Looping exercise, , Recursion, Loops & Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11512 @section Looping Exercise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11513
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11514 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11515 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11516 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
11517 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
11518
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11519 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11520 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
11521 adds the values.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11522
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11523 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11524 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
11525 using @code{cond}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11526
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11527 @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
11528 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11529 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
11530 beginning of a paragraph for every @samp{@@dfn} within the paragraph.
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
11531 (In a Texinfo file, @samp{@@dfn} marks a definition. This book is
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
11532 written in Texinfo.)
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
11533
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
11534 Many of the functions you will need are described in two of the
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
11535 previous chapters, @ref{Cutting & Storing Text, , Cutting and Storing
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
11536 Text}, and @ref{Yanking, , Yanking Text Back}. If you use
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
11537 @code{forward-paragraph} to put the index entry at the beginning of
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
11538 the paragraph, you will have to use @w{@kbd{C-h f}}
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
11539 (@code{describe-function}) to find out how to make the command go
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
11540 backwards.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
11541
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
11542 For more information, see
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11543 @ifinfo
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
11544 @ref{Indicating, , Indicating Definitions, texinfo}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11545 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11546 @ifhtml
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
11547 @ref{Indicating, , Indicating, texinfo, Texinfo Manual}, which goes to
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
11548 a Texinfo manual in the current directory. Or, if you are on the
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
11549 Internet, see
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
11550 @uref{http://www.gnu.org/manual/texinfo-4.6/html_node/Indicating.html}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11551 @end ifhtml
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11552 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11553 ``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
11554 Documentation Format}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11555 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11556 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11557
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11558 @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
11559 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11560 @chapter Regular Expression Searches
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11561 @cindex Searches, illustrating
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11562 @cindex Regular expression searches
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11563 @cindex Patterns, searching for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11564 @cindex Motion by sentence and paragraph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11565 @cindex Sentences, movement by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11566 @cindex Paragraphs, movement by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11567
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11568 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
11569 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
11570 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
11571 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
11572 as `regexp'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11573
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11574 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
11575 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
11576 @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
11577 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
11578 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
11579 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
11580 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
11581 @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
11582 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
11583 that spot.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11584
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11585 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
11586 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
11587 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
11588 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
11589 @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
11590 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
11591 @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
11592 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
11593 introduces several new features.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11594
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11595 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11596 * 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
11597 * 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
11598 * 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
11599 * forward-paragraph:: A somewhat complex example.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11600 * 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
11601 * Regexp Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11602 * re-search Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11603 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11604
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11605 @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
11606 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11607 @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
11608 @findex sentence-end
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 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
11611 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
11612
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11613 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
11614 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
11615 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
11616 the pattern should include the character set:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11617
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11618 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11619 [.?!]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11620 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11621
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11622 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
11623 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
11624 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
11625 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
11626
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11627 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
11628 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
11629 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
11630 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
11631 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
11632 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
11633 items as alternatives.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11634
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11635 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11636 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
11637
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11638 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11639 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11640 \\($\\| \\| \\)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11641 ^ ^^
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11642 TAB SPC
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11643 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11644 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11645
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11646 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11647 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
11648 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
11649 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
11650
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11651 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
11652 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
11653 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
11654 parenthesis or the vertical bar, is special.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11655
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11656 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11657 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
11658 this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11661 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11662 [
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11663 ]*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11664 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11665 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11666
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11667 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11668 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
11669 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
11670 @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
11671
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11672 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
11673 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
11674 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
11675 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
11676 expression that looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11677
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11678 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11679 []\"')@}]*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11680 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11681
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11682 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
11683 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
11684 @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
11685 three characters are @samp{'}, @samp{)}, and @samp{@}}.
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 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
11688 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
11689 @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
11690
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11691 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11692 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11693 sentence-end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11694 @result{} "[.?!][]\"')@}]*\\($\\| \\| \\)[
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11695 ]*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11696 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11697 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11698
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11699 @ignore
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11702 (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
11703 literally in the pattern.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11704
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11705 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
11706
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11707 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11708 @item [.?!]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11709 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
11710 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
11711 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
11712
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11713 @item []\"')@}]*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11714 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
11715 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
11716 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
11717 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
11718 @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
11719 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
11720 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
11721 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
11722 more times.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11723
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11724 @item \\($\\| \\| \\)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11725 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
11726 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
11727 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
11728 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
11729 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
11730 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
11731 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
11732 indicate what they are.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11733
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11734 @item [@key{RET}]*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11735 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
11736 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
11737 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
11738 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
11739 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
11740 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11741
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11742 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11743
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11744 @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
11745 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11746 @section The @code{re-search-forward} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11747 @findex re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11748
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11749 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
11750 @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
11751 @code{search-forward} Function}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11752
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11753 @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
11754 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
11755 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
11756 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
11757 @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
11758 is therefore a `side effect'.)
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 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
11761 four arguments:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11762
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11763 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11764 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11765 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
11766 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
11767
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11768 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11769 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
11770 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
11771
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11772 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11773 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
11774 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
11775 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
11776 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
11777 if the search succeeds.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11778
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11779 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11780 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
11781 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
11782 @end enumerate
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11785 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
11786
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11787 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11788 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11789 (re-search-forward "@var{regular-expression}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11790 @var{limit-of-search}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11791 @var{what-to-do-if-search-fails}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11792 @var{repeat-count})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11793 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11794 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11795
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11796 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
11797 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
11798 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
11799 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
11800 to.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11801
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11802 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11803 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
11804 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
11805
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11806 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11807 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11808 "[.?!][]\"')@}]*\\($\\| \\| \\)[
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11809 ]*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11810 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11811 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11812
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11813 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11814 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
11815 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
11816 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
11817 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
11818
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11819 @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
11820 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11821 @section @code{forward-sentence}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11822 @findex forward-sentence
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11823
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11824 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
11825 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
11826 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
11827 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
11828 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
11829 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
11830
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11831 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11832 * Complete forward-sentence::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11833 * 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
11834 * 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
11835 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11836
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11837 @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
11838 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11839 @unnumberedsubsec Complete @code{forward-sentence} function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11840 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11841
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11842 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11843 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
11844
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11845 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11846 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11847 (defun forward-sentence (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11848 "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
11849 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
11850 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
11851 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
11852 terminates sentences as well."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11853 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11854 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11855 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11856 (or arg (setq arg 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11857 (while (< arg 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11858 (let ((par-beg
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11859 (save-excursion (start-of-paragraph-text) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11860 (if (re-search-backward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11861 (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
11862 (goto-char (1- (match-end 0)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11863 (goto-char par-beg)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11864 (setq arg (1+ arg)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11865 (while (> arg 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11866 (let ((par-end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11867 (save-excursion (end-of-paragraph-text) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11868 (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
11869 (skip-chars-backward " \t\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11870 (goto-char par-end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11871 (setq arg (1- arg))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11872 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11873 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11874
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11875 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
11876 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
11877 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
11878
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11879 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11880 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11881 (defun forward-sentence (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11882 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11883 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11884 (or arg (setq arg 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11885 (while (< arg 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11886 @var{body-of-while-loop}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11887 (while (> arg 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11888 @var{body-of-while-loop}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11889 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11890 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11891
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11892 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
11893 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
11894 expression, and @code{while} loops.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11895
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11896 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
11897
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11898 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
11899
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11900 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
11901 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
11902 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
11903 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
11904 @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
11905 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
11906 @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11907
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11908 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
11909 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
11910 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
11911 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
11912
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11913 @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
11914 @unnumberedsubsec The @code{while} loops
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 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
11917 @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
11918 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
11919 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
11920 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
11921 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
11922 loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11923
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11924 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11925 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
11926 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11927
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11928 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11929 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11930 (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
11931 (let @var{varlist}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11932 (if (@var{true-or-false-test})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11933 @var{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11934 @var{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11935 (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
11936 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11937 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11938
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11939 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
11940 (@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
11941 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
11942 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
11943 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
11944 the loop repeats.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11945
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11946 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
11947 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
11948 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
11949
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11950 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
11951 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
11952 @code{if} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11953
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11954 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11955 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
11956
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11957 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11958 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11959 (let ((par-end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11960 (save-excursion (end-of-paragraph-text) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11961 (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
11962 (skip-chars-backward " \t\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11963 (goto-char par-end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11964 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11965 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11966
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11967 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
11968 @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
11969 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
11970 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
11971 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
11972
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11973 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
11974 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
11975 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
11976 evaluates the expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11977
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11978 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11979 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11980 (save-excursion (end-of-paragraph-text) (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11981 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11982 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11983
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11984 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11985 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
11986 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
11987 @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
11988 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
11989 @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
11990 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
11991 @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
11992
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11993 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11994 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
11995 expression that looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11996
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11997 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11998 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11999 (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
12000 (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
12001 (goto-char par-end))) ; @r{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12002 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12003 @end smallexample
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{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
12006 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
12007 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
12008 expression is the regular expression search.
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 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
12011 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
12012 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
12013
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12014 @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
12015 @unnumberedsubsec The regular expression search
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12016
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12017 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
12018 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
12019 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
12020 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
12021
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12022 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12023 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12024 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
12025 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
12026
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12027 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12028 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
12029 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
12030 successful.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12031 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12032
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12033 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12034 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
12035 @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
12036 conclusion of the search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12037
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12038 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
12039 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
12040 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
12041 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
12042 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
12043 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
12044 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
12045 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
12046 usually a period.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12047
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12048 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
12049 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
12050 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
12051 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
12052 end of the paragraph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12053
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12054 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
12055 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
12056 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
12057 incorporating this pattern often.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12058
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12059 @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
12060 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12061 @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
12062 @findex forward-paragraph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12063
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12064 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
12065 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
12066 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
12067 @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
12068
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12069 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
12070 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
12071 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
12072 fill prefix.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12073
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12074 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
12075 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
12076 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
12077 @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
12078 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
12079 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
12080 prefixes.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12081
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12082 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
12083 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
12084 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
12085 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
12086 with the fill prefix.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12087
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12088 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
12089 exists, especially when blank lines separate paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12090 This is an added complication.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12091
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12092 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12093 * 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
12094 * fwd-para let:: The @code{let*} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12095 * 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
12096 * fwd-para between paragraphs:: Movement between paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12097 * fwd-para within paragraph:: Movement within paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12098 * 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
12099 * 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
12100 * 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
12101 @end menu
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 @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
12104 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12105 @unnumberedsubsec Shortened @code{forward-paragraph} function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12106 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12107
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12108 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
12109 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
12110 can be daunting!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12111
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12112 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12113 In outline, the function looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12114
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12115 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12116 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12117 (defun forward-paragraph (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12118 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12119 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12120 (or arg (setq arg 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12121 (let*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12122 @var{varlist}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12123 (while (< arg 0) ; @r{backward-moving-code}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12124 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12125 (setq arg (1+ arg)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12126 (while (> arg 0) ; @r{forward-moving-code}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12127 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12128 (setq arg (1- arg)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12129 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12130 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12131
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12132 The 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
12133 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
12134
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12135 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
12136 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
12137 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
12138 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
12139 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
12140 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
12141 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
12142 @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
12143 familiar part of this function.
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 @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
12146 @unnumberedsubsec The @code{let*} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12147
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12148 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
12149 @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
12150 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
12151
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12152 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
12153 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
12154 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
12155 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
12156
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12157 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
12158 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
12159 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
12160 value of @code{fill-prefix-regexp}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12161
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12162 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12163 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
12164 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
12165
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12166 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12167 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12168 (and fill-prefix
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12169 (not (equal fill-prefix ""))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12170 (not paragraph-ignore-fill-prefix)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12171 (regexp-quote fill-prefix))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12172 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12173 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12174
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12175 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12176 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
12177
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12178 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
12179 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
12180 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
12181 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
12182 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
12183 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
12184 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
12185 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
12186 arguments are true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12187 @findex and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12188
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12189 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
12190 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
12191 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
12192 @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
12193
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12194 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12195 @item fill-prefix
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12196 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
12197 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
12198 @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12199
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12200 @item (not (equal fill-prefix "")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12201 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
12202 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
12203 not a useful fill prefix.
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 @item (not paragraph-ignore-fill-prefix)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12206 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
12207 @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
12208 true value such as @code{t}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12209
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12210 @item (regexp-quote fill-prefix)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12211 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
12212 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
12213 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
12214 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
12215 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12216
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12217 @findex regexp-quote
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12218 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12219 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
12220 @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
12221 @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
12222 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
12223 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
12224 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
12225 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
12226 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
12227
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12228 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
12229 @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
12230 evaluating the expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12231
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12232 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12233 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12234 (if fill-prefix-regexp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12235 (concat paragraph-separate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12236 "\\|^" fill-prefix-regexp "[ \t]*$")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12237 paragraph-separate)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12238 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12239 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12240
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12241 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
12242 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
12243 @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
12244
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12245 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
12246 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
12247 @code{paragraph-separate} to its local value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12248 (@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
12249 separates paragraphs.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12251 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
12252 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
12253 @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
12254 @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
12255
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12256 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
12257 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
12258 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
12259 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
12260 @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
12261 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
12262 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
12263 @code{paragraph-separate}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12264
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12265 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
12266 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
12267 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
12268 section.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12269
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12270 @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
12271 @unnumberedsubsec The forward motion @code{while} loop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12272
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12273 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
12274 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
12275 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
12276 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
12277 @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
12278 forward one paragraph.
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 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
12281 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
12282 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
12283
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12284 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12285 The @code{while} loop looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12286
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12287 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12288 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12289 (while (> arg 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12290 (beginning-of-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12291
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12292 ;; @r{between paragraphs}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12293 (while (prog1 (and (not (eobp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12294 (looking-at paragraph-separate))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12295 (forward-line 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12296 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12297
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12298 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12299 ;; @r{within paragraphs, with a fill prefix}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12300 (if fill-prefix-regexp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12301 ;; @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
12302 (while (and (not (eobp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12303 (not (looking-at paragraph-separate))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12304 (looking-at fill-prefix-regexp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12305 (forward-line 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12306 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12307
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12308 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12309 ;; @r{within paragraphs, no fill prefix}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12310 (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
12311 (goto-char (match-beginning 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12312 (goto-char (point-max))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12313
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12314 (setq arg (1- arg)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12315 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12316 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12317
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12318 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
12319 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
12320
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12321 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12322 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
12323
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12324 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12325 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12326 ;; @r{between paragraphs}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12327 (beginning-of-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12328 (while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12329 @var{body-of-while})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12330 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12333 ;; @r{within paragraphs, with fill prefix}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12334 (if @var{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12335 @var{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12336 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12337
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12338 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12339 ;; @r{within paragraphs, no fill prefix}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12340 @var{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12341 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12342 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12343
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12344 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12345 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
12346 @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
12347 @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
12348 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
12349 @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
12350 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
12351 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
12352 of the paragraph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12353
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12354 @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
12355 @unnumberedsubsec Between paragraphs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12356
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12357 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
12358 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
12359 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
12360 @findex prog1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12361 @findex eobp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12362 @findex looking-at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12363
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12364 @itemize @bullet
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{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
12367 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
12368 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
12369 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
12370 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
12371 @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
12372
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12373 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12374 @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
12375 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
12376
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12377 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12378 @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
12379 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
12380 argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12381 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12382
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12383 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12384 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
12385
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12386 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12387 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12388 (while (prog1 (and (not (eobp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12389 (looking-at paragraph-separate))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12390 (forward-line 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12391 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12392 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12393
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12394 @need 1200
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 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
12397 loop is the expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12398
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12399 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12400 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12401 (prog1 (and (not (eobp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12402 (looking-at paragraph-separate))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12403 (forward-line 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12404 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12405 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12406
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12407 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12408 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
12409 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
12410 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
12411 expression for separating paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12412
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12413 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
12414 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
12415 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
12416 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
12417 @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
12418 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
12419 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
12420 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
12421 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
12422 @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
12423 @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
12424 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
12425 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
12426
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12427 @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
12428 @unnumberedsubsec Within paragraphs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12429
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12430 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
12431 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
12432 @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
12433 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
12434 @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
12435 fill prefix.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12436
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12437 @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
12438 @unnumberedsubsec No fill prefix
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 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
12441 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
12442 expression, and reads as follows:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12443
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12444 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12445 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12446 (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
12447 (goto-char (match-beginning 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12448 (goto-char (point-max)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12449 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12450 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12451
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12452 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12453 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
12454 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
12455 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
12456 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
12457 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
12458 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
12459
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12460 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
12461 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
12462 @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
12463 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
12464 expression search.
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 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
12467 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
12468 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
12469 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
12470 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
12471 @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
12472 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
12473
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12474 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
12475 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
12476 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
12477
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12478 @findex match-beginning
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12479 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
12480 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
12481 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
12482 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
12483 @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
12484 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
12485 of the paragraph.
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 (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
12488 @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
12489 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
12490
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12491 @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
12492 @unnumberedsubsec With a fill prefix
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12493
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12494 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
12495 @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
12496 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
12497 It looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12498
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12499 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12500 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12501 (while (and (not (eobp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12502 (not (looking-at paragraph-separate))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12503 (looking-at fill-prefix-regexp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12504 (forward-line 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12505 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12506 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12507
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12508 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12509 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
12510 as three conditions are true:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12511
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12512 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12513 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12514 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
12515
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12516 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12517 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
12518
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12519 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12520 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
12521 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12522
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12523 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
12524 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
12525 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
12526 @code{looking-at} function will see it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12527
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12528 @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
12529 @unnumberedsubsec Summary
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12530
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12531 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
12532 does the following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12533
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12534 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12535 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12536 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
12537
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12538 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12539 Skip over lines between paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12540
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12541 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12542 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
12543
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12544 @itemize ---
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12545
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12546 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12547 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
12548 separating line.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12549 @end itemize
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 But if there is no fill prefix,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12553
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12554 @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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12557 Search for the next paragraph start pattern.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12558
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12559 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12560 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
12561 end of the previous paragraph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12562
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12563 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12564 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
12565 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12566 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12567
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12568 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12569 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
12570 for clarity:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12571
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12572 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12573 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12574 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12575 (or arg (setq arg 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12576 (let* (
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12577 (fill-prefix-regexp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12578 (and fill-prefix (not (equal fill-prefix ""))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12579 (not paragraph-ignore-fill-prefix)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12580 (regexp-quote fill-prefix)))
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 (paragraph-separate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12585 (if fill-prefix-regexp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12586 (concat paragraph-separate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12587 "\\|^"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12588 fill-prefix-regexp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12589 "[ \t]*$")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12590 paragraph-separate)))
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 @var{omitted-backward-moving-code} @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12593 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12594
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12595 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12596 (while (> arg 0) ; @r{forward-moving-code}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12597 (beginning-of-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12598
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12599 (while (prog1 (and (not (eobp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12600 (looking-at paragraph-separate))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12601 (forward-line 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12602 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12603
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12604 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12605 (if fill-prefix-regexp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12606 (while (and (not (eobp)) ; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12607 (not (looking-at paragraph-separate))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12608 (looking-at fill-prefix-regexp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12609 (forward-line 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12610 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12611 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12612 ; @r{else-part: the inner-if}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12613 (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
12614 (goto-char (match-beginning 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12615 (goto-char (point-max))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12616
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12617 (setq arg (1- arg))))) ; @r{decrementer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12618 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12619 @end smallexample
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 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
12622 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
12623
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12624 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
12625 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
12626 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
12627 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
12628 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
12629 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
12630 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
12631 a car with his eyes shut!)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12632
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12633 @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
12634 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
12635 (@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
12636 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
12637 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
12638 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
12639 @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
12640 @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
12641
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12642 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
12643 lack one.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12644 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12645 @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
12646 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12647
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12648 @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
12649 @section Create Your Own @file{TAGS} File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12650 @findex etags
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12651 @cindex @file{TAGS} file, create own
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12652
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12653 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
12654 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
12655 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
12656
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12657 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
12658 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
12659 the name is in upper case letters.
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 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
12662 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
12663 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
12664 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
12665
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12666 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12667 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
12668 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
12669 @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
12670 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
12671 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
12672
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12673 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12674 M-x compile RET etags *.el RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12675 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12676
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12677 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12678 to create a @file{TAGS} file.
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 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
12681 @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
12682 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
12683 Lisp files in that directory.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12684
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12685 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12686 The @code{etags} program takes all the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12687 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
12688 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
12689 @w{@code{etags *.el ../elisp/*.el}},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12690 where @file{../elisp/} is the second directory:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12691
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12692 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12693 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
12694 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12695
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12696 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12697 Type
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12698
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12699 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12700 M-x compile RET etags --help RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12701 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12702
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12703 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12704 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
12705 list of supported languages.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12706
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12707 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
12708 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
12709 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
12710 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
12711 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
12712
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12713 @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
12714 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
12715 @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
12716 become part of the @file{TAGS} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12717
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12718 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
12719 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
12720 program to attempt to find it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12721
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12722 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
12723 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
12724 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
12725 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
12726 files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12727
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12728 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
12729 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
12730 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
12731 visit-tags-table}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12732
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12733 @subsubheading Building Tags in the Emacs sources
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12734 @cindex Building Tags in the Emacs sources
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12735 @cindex Tags in the Emacs sources
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12736 @findex make tags
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12737
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12738 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
12739 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
12740 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
12741 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
12742 level of your Emacs source directory.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12745 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
12746 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
12747
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12748 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12749 M-x compile RET make tags RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12750 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12751
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12752 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12753 (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
12754 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
12755
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12756 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
12757 Manual}.
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 @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
12760 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12761 @section Review
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12762
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12763 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
12764
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12765 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12766 @item while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12767 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
12768 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
12769 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
12770
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12771 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12772 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12773
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12774 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12775 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12776 (let ((foo 2))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12777 (while (> foo 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12778 (insert (format "foo is %d.\n" foo))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12779 (setq foo (1- foo))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12780
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12781 @result{} foo is 2.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12782 foo is 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12783 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12784 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12785 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12786 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12787 (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
12788 @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
12789 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
12790 line.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12791
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12792 @item re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12793 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
12794 just after it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12795
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12796 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12797 Takes four arguments, like @code{search-forward}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12798
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12799 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12800 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12801 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
12802
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12803 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12804 Optionally, the limit of the search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12805
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12806 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12807 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
12808 error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12809
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12810 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12811 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
12812 search goes backwards.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12813 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12814
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12815 @item let*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12816 Bind some variables locally to particular values,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12817 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
12818 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
12819 variables bound earlier, if any.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12822 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12823
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12824 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12825 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12826 (let* ((foo 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12827 (bar (* 3 foo)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12828 (message "`bar' is %d." bar))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12829 @result{} `bar' is 21.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12830 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12831 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12832
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12833 @item match-beginning
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12834 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
12835 expression search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12836
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12837 @item looking-at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12838 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
12839 which should be a regular expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12840
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12841 @item eobp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12842 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
12843 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
12844 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
12845 the buffer is narrowed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12846
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12847 @item prog1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12848 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
12849 @emph{first}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12850
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12851 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12852 For example:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12855 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12856 (prog1 1 2 3 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12857 @result{} 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12858 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12859 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12860 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12861
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12862 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12863 @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
12864 @section Exercises with @code{re-search-forward}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12865
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12866 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12867 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12868 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
12869 or more blank lines in sequence.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12870
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12871 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12872 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
12873 @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
12874 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
12875 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
12876 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
12877 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
12878 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
12879 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12880
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12881 @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
12882 @chapter Counting: Repetition and Regexps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12883 @cindex Repetition for word counting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12884 @cindex Regular expressions for word counting
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 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
12887 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
12888 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
12889 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
12890
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12891 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12892 * Why Count Words::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12893 * 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
12894 * 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
12895 * Counting Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12896 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12897
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12898 @node 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
12899 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12900 @unnumberedsec Counting words
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12901 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12902
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12903 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
12904 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
12905 function for counting words.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12906
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12907 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
12908 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
12909 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
12910 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
12911 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
12912 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
12913 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
12914 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
12915 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
12916 commands to count words.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12917
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12918 @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
12919 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12920 @section The @code{count-words-region} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12921 @findex count-words-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12922
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12923 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
12924 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
12925 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
12926 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
12927 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
12928 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
12929 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
12930 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
12931 h} (@code{mark-whole-buffer}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12932
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12933 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
12934 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
12935 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
12936 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
12937 or to a @code{while} loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12938
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12939 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12940 * 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
12941 * 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
12942 @end menu
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 @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
12945 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12946 @unnumberedsubsec Designing @code{count-words-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12947 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12948
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12949 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
12950 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
12951 interactive.
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12954 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
12955
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12956 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12957 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12958 (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
12959 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12960 (@var{interactive-expression}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12961 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12962 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12963 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12964
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12965 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
12966
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12967 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
12968 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
12969 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
12970
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12971 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
12972 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
12973 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
12974 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
12975 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
12976 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
12977 @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
12978 @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
12979 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
12980 this is routine.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12981
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12982 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
12983 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
12984 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
12985 a message to the user.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12986
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12987 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
12988 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
12989 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
12990 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
12991 @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
12992 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
12993 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
12994 @code{save-excursion} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12995
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12996 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
12997 @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
12998 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
12999 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
13000 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
13001
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13002 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
13003 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
13004 `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
13005
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13006 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
13007 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
13008 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
13009 word by word.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13010
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13011 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
13012 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
13013 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
13014 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
13015 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
13016 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
13017 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
13018 the regexp must be optional.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13019
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13020 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
13021 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
13022 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
13023 this is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13024
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13025 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13026 \w+\W*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13027 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13028
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13029 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13030 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
13031 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
13032 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
13033 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
13034 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
13035
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13036 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13037 The search expression looks like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13040 (re-search-forward "\\w+\\W*")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13041 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13044 (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
13045 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
13046 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
13047 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
13048 @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
13049 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
13050
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13051 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
13052 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
13053 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
13054
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13055 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13056 (setq count (1+ count))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13057 @end smallexample
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 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
13060 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
13061 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
13062 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
13063 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
13064 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
13065 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
13066 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
13067 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
13068 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
13069 special form is appropriate.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13070
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13071 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13072 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
13073
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13074 @smallexample
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{First version; has bugs!}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13077 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13078 "Print number of words in the region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13079 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
13080 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
13081 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
13082 table determines which characters these are."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13083 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13084 (message "Counting words in region ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13085 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13086
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13087 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13088 ;;; @r{1. Set up appropriate conditions.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13089 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13090 (goto-char beginning)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13091 (let ((count 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13092 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13093
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13094 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13095 ;;; @r{2. Run the} while @r{loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13096 (while (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13097 (re-search-forward "\\w+\\W*")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13098 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13099 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13101 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13102 ;;; @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
13103 (cond ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13104 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13105 "The region does NOT have any words."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13106 ((= 1 count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13107 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13108 "The region has 1 word."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13109 (t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13110 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13111 "The region has %d words." count))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13112 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13113 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13114
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13115 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13116 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
13117
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13118 @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
13119 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13120 @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
13121
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13122 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
13123 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
13124 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
13125 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
13126 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
13127 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
13128 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
13129 like this:
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 Search failed: "\\w+\\W*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13133 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13134
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13135 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
13136 bugs yourself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13137
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13138 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
13139 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13140 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
13141 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
13142
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13143 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13144 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13145 ;; @r{First version; has bugs!}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13146 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13147 "Print number of words in the region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13148 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
13149 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
13150 syntax table determines which characters these are."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13151 @end group
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 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13154 (message "Counting words in region ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13155 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13156
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13157 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13158 ;;; @r{1. Set up appropriate conditions.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13159 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13160 (goto-char beginning)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13161 (let ((count 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13162 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13163
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13164 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13165 ;;; @r{2. Run the} while @r{loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13166 (while (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13167 (re-search-forward "\\w+\\W*")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13168 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13169 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13170
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13171 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13172 ;;; @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
13173 (cond ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13174 (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
13175 ((= 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
13176 (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
13177 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13178 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13179 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13180
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13181 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13182 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
13183
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13184 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13185 (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
13186 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13187
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13188 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
13189 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
13190 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
13191
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13192 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13193 one two three
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13194 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13195
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13196 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13197 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
13198
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13199 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
13200 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
13201 @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
13202 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
13203 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
13204 that the region has one word!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13205
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13206 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
13207 @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
13208 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
13209 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
13210 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
13211 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
13212 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
13213 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
13214
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13215 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
13216
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13217 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
13218 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
13219 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
13220 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
13221 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
13222 @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
13223 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
13224 @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
13225 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
13226 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
13227 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
13228 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
13229 the marked region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13230
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13231 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
13232 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
13233 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
13234 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
13235 in the buffer, the search fails.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13236
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13237 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
13238 extend outside of the region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13239
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13240 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
13241 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
13242 simple as you might think.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13243
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13244 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
13245 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
13246 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
13247 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
13248 @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
13249 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
13250 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
13251 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
13252
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13253 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
13254 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
13255 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
13256 to the regular expression search expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13257
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13258 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13259 (re-search-forward "\\w+\\W*" end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13260 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13261
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13262 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
13263 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
13264 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
13265 @samp{Search failed}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13266
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13267 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
13268 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
13269 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
13270 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
13271 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
13272
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13273 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
13274 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
13275 @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
13276
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13277 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
13278 ``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
13279 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
13280
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13281 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
13282 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
13283 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
13284 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
13285 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
13286 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
13287 @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
13288 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
13289 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
13290 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
13291 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
13292
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13293 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
13294 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
13295 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
13296 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
13297 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
13298 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
13299
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13300 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
13301 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
13302 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
13303 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
13304
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13305 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13306 (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
13307 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13308
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13309 @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
13310 @c also trouble with an overfull hbox
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13311 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13312 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13313 (For information about @code{and}, see
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13314 @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
13315 Functions}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13316 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13317 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13318 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13319 (@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
13320 @end ifinfo
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 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
13323 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
13324 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
13325 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
13326 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
13327 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
13328 or other of its messages.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13329
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13330 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
13331 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
13332 Here is what it looks like:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13333
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13334 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13335 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13336 ;;; @r{Final version:} @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13337 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13338 "Print number of words in the region."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13339 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13340 (message "Counting words in region ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13341 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13342
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13343 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13344 ;;; @r{1. Set up appropriate conditions.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13345 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13346 (let ((count 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13347 (goto-char beginning)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13348 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13349
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13350 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13351 ;;; @r{2. Run the} while @r{loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13352 (while (and (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13353 (re-search-forward "\\w+\\W*" end t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13354 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13355 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13356
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13357 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13358 ;;; @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
13359 (cond ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13360 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13361 "The region does NOT have any words."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13362 ((= 1 count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13363 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13364 "The region has 1 word."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13365 (t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13366 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13367 "The region has %d words." count))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13368 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13369 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13370
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13371 @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
13372 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13373 @section Count Words Recursively
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13374 @cindex Count words recursively
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13375 @cindex Recursively counting words
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13376 @cindex Words, counted recursively
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13377
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13378 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
13379 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
13380
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13381 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
13382 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
13383 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
13384 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
13385
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13386 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
13387 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
13388 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
13389 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
13390 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
13391 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
13392 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
13393
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13394 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
13395 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
13396
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13397 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
13398 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
13399 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
13400 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
13401
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13402 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13403 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
13404 previous versions:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13405
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13406 @smallexample
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 ;; @r{Recursive version; uses regular expression search}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13409 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13410 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13411 (@var{interactive-expression}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13412 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13413 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13414
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13415 ;;; @r{1. Set up appropriate conditions.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13416 (@var{explanatory message})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13417 (@var{set-up functions}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13418 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13419 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13420
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13421 ;;; @r{2. Count the words.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13422 @var{recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13423 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13424 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13425
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13426 ;;; @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
13427 @var{message providing word count}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13428 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13429 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13430
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13431 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
13432 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
13433 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
13434 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
13435 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
13436 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
13437 @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
13438 user.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13439
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13440 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
13441 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
13442 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
13443 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
13444
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13445 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13446 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
13447
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13448 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13449 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13450 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13451 "Print number of words in the region."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13452 (interactive "r")
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{1. Set up appropriate conditions.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13457 (message "Counting words in region ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13458 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13459 (goto-char beginning)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13460 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13461
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13462 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13463 ;;; @r{2. Count the words.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13464 (let ((count (recursive-count-words end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13465 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13466
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13467 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13468 ;;; @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
13469 (cond ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13470 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13471 "The region does NOT have any words."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13472 ((= 1 count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13473 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13474 "The region has 1 word."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13475 (t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13476 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13477 "The region has %d words." count))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13478 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13479 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13480
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13481 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
13482
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13483 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
13484 `next-step-expression', and the recursive call.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13485
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13486 The 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
13487 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
13488 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
13489 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
13490 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
13491 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
13492 @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
13493 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
13494 argument.
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 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
13497 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
13498
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13499 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
13500 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
13501 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
13502 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
13503 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
13504 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
13505
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13506 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
13507
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13508 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
13509 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
13510
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13511 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13512 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
13513
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13514 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13515 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13516 (defun recursive-count-words (region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13517 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13518 @var{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13519 @var{next-step-expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13520 @var{recursive call})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13521 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13522 @end smallexample
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 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
13525 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
13526 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
13527 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
13528 function should return zero.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13529
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13530 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
13531 succeeds, the function should call itself again.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13532
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13533 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13534 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
13535
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13536 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13537 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13538 (and (< (point) region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13539 (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
13540 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13541 @end smallexample
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 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
13544 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
13545 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
13546 @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
13547 @code{re-search-forward} works.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13548
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13549 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
13550 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
13551 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
13552 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
13553 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
13554
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13555 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
13556 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
13557 part of the do-again-test.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13558
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13559 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
13560 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
13561 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
13562 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
13563 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
13564 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
13565
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13566 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13567 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
13568 function looks like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13571 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13572 (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
13573 ;; @r{then}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13574 @var{recursive-call-returning-count}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13575 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13576 @var{return-zero})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13577 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13578 @end smallexample
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 How to incorporate the mechanism that counts?
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 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
13583 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
13584 systematically.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13585
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13586 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
13587 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
13588 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
13589 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
13590 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
13591
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13592 Consider several cases:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13593
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13594 @itemize @bullet
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 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
13597 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
13598 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
13599 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
13600
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13601 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13602 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
13603 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
13604 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
13605 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
13606
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13607 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13608 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
13609 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13610
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13611 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
13612 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
13613 @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
13614 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
13615
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13616 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13617 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
13618 adds one to its argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13619
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13620 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13621 (1+ (recursive-count-words region-end))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13622 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13623
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13624 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13625 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
13626 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13627
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13628 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13629 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13630 (defun recursive-count-words (region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13631 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13632
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13633 ;;; @r{1. do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13634 (if (and (< (point) region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13635 (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
13636 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13639 ;;; @r{2. then-part: the recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13640 (1+ (recursive-count-words region-end))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13641
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13642 ;;; @r{3. else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13643 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13644 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13645 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13646
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13647 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13648 Let's examine how this works:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13649
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13650 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
13651 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
13652
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13653 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
13654 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
13655 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
13656 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
13657 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
13658 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
13659 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
13660
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13661 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
13662 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
13663 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
13664 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
13665 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
13666 @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
13667 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
13668 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
13669
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13670 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
13671 @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
13672 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
13673 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
13674 the correct amount.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13675
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13676 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
13677 @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
13678 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
13679 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
13680
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13681 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13682 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13683 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
13684
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13685 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13686 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13687 The recursive function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13688
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13689 @findex recursive-count-words
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13690 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13691 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13692 (defun recursive-count-words (region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13693 "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
13694 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13695
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13696 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13697 ;;; @r{1. do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13698 (if (and (< (point) region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13699 (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
13700 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13701
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13702 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13703 ;;; @r{2. then-part: the recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13704 (1+ (recursive-count-words region-end))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13705
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13706 ;;; @r{3. else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13707 0))
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 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13710
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13711 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13712 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13713 The wrapper:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13714
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13715 @smallexample
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 ;;; @r{Recursive version}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13718 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13719 "Print number of words in the region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13720 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13721
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13722 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13723 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
13724 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
13725 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
13726 determines which characters these are."
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 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13730 (message "Counting words in region ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13731 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13732 (goto-char beginning)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13733 (let ((count (recursive-count-words end)))
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13736 (cond ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13737 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13738 "The region does NOT have any words."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13739 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13740 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13741 ((= 1 count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13742 (message "The region has 1 word."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13743 (t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13744 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13745 "The region has %d words." count))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13746 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13747 @end smallexample
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 @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
13750 @section Exercise: Counting Punctuation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13751
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13752 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
13753 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
13754 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
13755
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13756 @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
13757 @chapter Counting Words in a @code{defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13758 @cindex Counting words in a @code{defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13759 @cindex Word counting in a @code{defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13760
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13761 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
13762 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
13763 @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
13764 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
13765 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
13766 @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
13767 @code{count-word-region}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13768
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13769 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
13770 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
13771 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
13772 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
13773 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
13774 and this will tell.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13775
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13776 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13777 * Divide and Conquer::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13778 * Words and Symbols:: What to count?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13779 * Syntax:: What constitutes a word or symbol?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13780 * 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
13781 * 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
13782 * 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
13783 * 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
13784 * 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
13785 * 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
13786 * 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
13787 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13788
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13789 @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
13790 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13791 @unnumberedsec Divide and Conquer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13792 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13793
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13794 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
13795 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
13796 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
13797 steps must be:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13798
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13799 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13800 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13801 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
13802 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
13803
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13804 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13805 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
13806 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
13807 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13808
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13809 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13810 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
13811 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
13812 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
13813 definitions within them.
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13816 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
13817 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
13818 a graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13819
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13820 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13821 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
13822 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13823
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13824 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
13825 be difficult.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13826
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13827 @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
13828 @section What to Count?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13829 @cindex Words and symbols in defun
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 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
13832 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
13833 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
13834 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
13835 `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
13836 function contains the five symbols @code{defun},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13837 @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
13838 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
13839 @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
13840 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
13841 of ten words and symbols.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13842
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13843 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13844 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13845 (defun multiply-by-seven (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13846 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13847 (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13848 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13849 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13850
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13851 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13852 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
13853 @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
13854 @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
13855 @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
13856 ten! Something is wrong!
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 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
13859 @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
13860 @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
13861 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
13862 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
13863 @samp{multiply by seven}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13864
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13865 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
13866 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
13867 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
13868 regexp is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13869
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13870 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13871 "\\w+\\W*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13872 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13873
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13874 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13875 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
13876 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
13877 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
13878 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
13879 of its own.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13880
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13881 @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
13882 @section What Constitutes a Word or Symbol?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13883 @cindex Syntax categories and tables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13884
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13885 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
13886 @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
13887 @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
13888 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
13889 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
13890 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
13891 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
13892 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
13893 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
13894 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
13895
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13896 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
13897 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
13898 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
13899 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
13900 @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
13901 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
13902 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
13903
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13904 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
13905 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
13906
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13907 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
13908 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
13909 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
13910 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
13911 constituent character; there are others, too.
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 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
13914 @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
13915 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
13916
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13917 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13918 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
13919 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
13920
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13921 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13922 "\\(\\w\\|\\s_\\)+"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13923 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13924
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13925 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13926 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
13927 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
13928 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
13929 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
13930 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
13931 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
13932 characters must be matched at least once.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13933
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13934 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
13935 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
13936 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
13937 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
13938
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13939 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13940 "\\(\\W\\|\\S_\\)*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13941 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13942
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13943 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13944 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
13945 @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
13946 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
13947 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
13948
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13949 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
13950 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
13951 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
13952 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
13953 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
13954 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
13955 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
13956 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
13957 then followed optionally by white space.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13958
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13959 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13960 Here is the full regular expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13961
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13962 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13963 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13964 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13965
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13966 @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
13967 @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
13968 @cindex Counting words in a @code{defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13969
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13970 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
13971 @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
13972 @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
13973 versions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13974
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13975 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
13976 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
13977 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
13978 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
13979 simplify the definition a little.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13980
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13981 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
13982 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
13983 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
13984 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
13985 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
13986 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
13987 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13988
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13989 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13990 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
13991
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13992 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13993 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13994 (defun count-words-in-defun ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13995 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13996 (@var{set up}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13997 (@var{while loop}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13998 @var{return count})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13999 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14000 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14003 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
14004
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14005 First, the set up.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14006
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14007 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
14008 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
14009 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
14010 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
14011 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
14012 end of the definition.
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{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
14015 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
14016 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
14017 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
14018 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
14019 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
14020 place point where we wish to start.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14021
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14022 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
14023 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
14024 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
14025
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14026 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
14027 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
14028 @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
14029 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
14030
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14031 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
14032 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
14033 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
14034 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
14035 looping.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14036
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14037 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14038 The code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14039
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14040 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14041 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14042 (beginning-of-defun)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14043 (let ((count 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14044 (end (save-excursion (end-of-defun) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14045 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14046 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14047
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14048 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14049 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
14050 @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
14051 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
14052 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
14053 definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14054
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14055 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
14056 is the @code{while} loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14057
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14058 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
14059 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
14060 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
14061 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
14062 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
14063 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
14064
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14065 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14066 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14067 (while (and (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14068 (re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14069 "\\(\\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
14070 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14071 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14072 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14073
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14074 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
14075 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
14076 @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
14077 @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
14078
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14079 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14080 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
14081
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14082 @findex count-words-in-defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14083 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14084 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14085 (defun count-words-in-defun ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14086 "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
14087 (beginning-of-defun)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14088 (let ((count 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14089 (end (save-excursion (end-of-defun) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14090 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14091 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14092 (while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14093 (and (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14094 (re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14095 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14096 end t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14097 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14098 count))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14099 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14100 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14101
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14102 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
14103 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
14104 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
14105 @code{count-words-region}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14106
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14107 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14108 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14109 ;;; @r{Interactive version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14110 (defun count-words-defun ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14111 "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
14112 (interactive)
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 "Counting words and symbols in function definition ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14115 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14116 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14117 (let ((count (count-words-in-defun)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14118 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14119 ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14120 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14121 "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
14122 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14123 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14124 ((= 1 count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14125 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14126 "The definition has 1 word or symbol."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14127 (t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14128 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14129 "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
14130 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14131 @end smallexample
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14134 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14135 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
14136
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14137 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14138 (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
14139 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14140
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14141 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
14142 @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
14143 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
14144
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14145 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14146 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14147 (defun multiply-by-seven (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14148 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14149 (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14150 @result{} 10
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14151 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14152 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14153
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14154 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14155 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
14156
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14157 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
14158 several definitions within a single file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14159
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14160 @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
14161 @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
14162
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14163 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
14164 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
14165 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
14166 statistics on one file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14167
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14168 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
14169 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
14170
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14171 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
14172 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
14173 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
14174 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
14175 messages.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14176
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14177 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
14178 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
14179 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
14180 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
14181 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
14182
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14183 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
14184 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
14185 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
14186 (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
14187 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
14188 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
14189 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
14190 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
14191 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
14192 is almost all there is to it.
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14195 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
14196
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14197 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14198 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14199 (goto-char (point-min))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14200 (while (re-search-forward "^(defun" nil t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14201 (setq lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14202 (cons (count-words-in-defun) lengths-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14203 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14204 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14205
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14206 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
14207 contains the function definitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14208
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14209 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
14210 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
14211 @file{*scratch*} buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14212
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14213 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
14214
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14215 @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
14216 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14217 @section Find a File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14218 @cindex Find a File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14219
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14220 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
14221 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
14222 problem.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14223
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14224 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14225 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
14226 @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
14227 find the source of a function):
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14228
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14229 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14230 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14231 (defun find-file (filename)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14232 "Edit file FILENAME.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14233 Switch to a buffer visiting file FILENAME,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14234 creating one if none already exists."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14235 (interactive "FFind file: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14236 (switch-to-buffer (find-file-noselect filename)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14237 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14238 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14239
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14240 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
14241 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
14242 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
14243 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
14244
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14245 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
14246 @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
14247 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
14248 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
14249 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
14250 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
14251 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
14252 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
14253 buffer switching elsewhere. (@xref{Switching Buffers}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14254
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14255 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
14256 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
14257 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
14258 @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
14259 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
14260 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
14261 our own expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14262
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14263 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
14264
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14265 @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
14266 @section @code{lengths-list-file} in Detail
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14267
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14268 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
14269 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
14270 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
14271 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
14272 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
14273 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
14274 @findex lengths-list-file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14275
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14276 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14277 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14278 (defun lengths-list-file (filename)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14279 "Return list of definitions' lengths within FILE.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14280 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
14281 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
14282 symbols in one function definition."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14283 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14284 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14285 (message "Working on `%s' ... " filename)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14286 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14287 (let ((buffer (find-file-noselect filename))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14288 (lengths-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14289 (set-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14290 (setq buffer-read-only t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14291 (widen)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14292 (goto-char (point-min))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14293 (while (re-search-forward "^(defun" nil t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14294 (setq lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14295 (cons (count-words-in-defun) lengths-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14296 (kill-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14297 lengths-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14298 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14299 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14302 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
14303 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
14304 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
14305 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
14306 message.
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 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
14309 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
14310 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
14311 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
14312
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14313 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
14314 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
14315 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
14316 variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14317
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14318 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
14319
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14320 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
14321 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
14322 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
14323 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
14324 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
14325 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
14326 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
14327 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
14328 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
14329 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
14330
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14331 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
14332 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
14333 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
14334 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
14335 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
14336 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
14337 won't.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14338
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14339 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
14340 beginning of the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14341
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14342 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
14343 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
14344 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
14345
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14346 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
14347 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
14348 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
14349 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
14350 files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14351
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14352 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
14353 @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
14354 the whole function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14355
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14356 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
14357 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
14358 C-e} (@code{eval-last-sexp}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14359
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14360 @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
14361 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14362 (lengths-list-file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14363 "/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
14364 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14365
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14366 @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
14367 @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
14368 @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
14369 @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
14370
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14371 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14372 (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
14373 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
14374 the @file{*scratch*} buffer and edit it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14375
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14376 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14377 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14378 (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
14379 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
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 (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
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 @noindent
53099
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
14386 (@xref{defcustom, , Specifying Variables using @code{defcustom}}.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14387 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
14388
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14389 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14390 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
14391 produce and looks like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14394 (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
14395 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14396
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14397 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14398 (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
14399 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
14400
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14401 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14402 (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
14403 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14404
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14405 (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
14406 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
14407
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14408 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
14409 the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14410
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14411 @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
14412 @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
14413
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14414 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
14415 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
14416 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
14417 a list of files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14418
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14419 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
14420 either a @code{while} loop or recursion.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14422 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14423 * 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
14424 * append:: Attach one list to another.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14425 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14426
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14427 @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
14428 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14429 @unnumberedsubsec Determine the lengths of @code{defuns}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14430 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14431
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14432 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
14433 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
14434 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
14435 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
14436 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
14437 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
14438 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
14439 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
14440 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
14441
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14442 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14443 The template looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14444
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14445 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14446 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14447 (while @var{test-whether-list-is-empty}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14448 @var{body}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14449 @var{set-list-to-cdr-of-list})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14450 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14451 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14452
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14453 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
14454 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
14455 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
14456 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
14457 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
14458 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
14459 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
14460 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
14461 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
14462 Example with an Incrementing Counter}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14463
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14464 @findex lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14465 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14466 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
14467
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14468 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14469 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14470 ;;; @r{Use @code{while} loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14471 (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
14472 "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
14473 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14474 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14475 (let (lengths-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14476
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14477 ;;; @r{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14478 (while list-of-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14479 (setq lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14480 (append
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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14483 ;;; @r{Generate a lengths' list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14484 (lengths-list-file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14485 (expand-file-name (car list-of-files)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14486 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14487
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14488 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14489 ;;; @r{Make files' list shorter.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14490 (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
14491
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14492 ;;; @r{Return final value of lengths' list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14493 lengths-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14494 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14495 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14496
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14497 @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
14498 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
14499 the function is called.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14501 @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
14502 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14503 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
14504 Emacs is visiting the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14505 @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
14506
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14507 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14508 debug.el
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14509 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14510
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14511 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14512 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14513 becomes
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 @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
14516 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14517 /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
14518 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14519
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14520 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
14521 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
14522 itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14523
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14524 @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
14525 @subsection The @code{append} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14526
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14527 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14528 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
14529
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14530 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14531 (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
14532 @end smallexample
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14535 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14536 produces the list
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14539 (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
14540 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14541
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14542 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
14543 @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
14544 @code{cons},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14545
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14546 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14547 (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
14548 @end smallexample
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14551 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14552 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
14553 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
14554
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14555 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14556 ((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
14557 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14558
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14559 @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
14560 @section Recursively Count Words in Different Files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14561
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14562 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
14563 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
14564 is short and simple.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14565
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14566 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
14567 `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
14568 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
14569 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
14570 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
14571 @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
14572 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
14573 function is shorter than this description!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14574 @findex recursive-lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14575
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14576 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14577 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14578 (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
14579 "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
14580 (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
14581 (append
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14582 (lengths-list-file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14583 (expand-file-name (car list-of-files)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14584 (recursive-lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14585 (cdr list-of-files)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14586 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14587 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14588
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14589 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14590 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
14591 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
14592 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
14593
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14594 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
14595 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
14596 individually.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14597
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14598 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
14599 @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
14600 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
14601 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
14602 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
14603 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
14604
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14605 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
14606 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
14607 Emacs may produce different results.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14608
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14609 @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
14610 @smallexample
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 (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
14613
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14614 (lengths-list-file "./lisp/macros.el")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14615 @result{} (273 263 456 90)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14616 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14617
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14618 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14619 (lengths-list-file "./lisp/mail/mailalias.el")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14620 @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
14621 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14622
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14623 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14624 (lengths-list-file "./lisp/makesum.el")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14625 @result{} (85 181)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14626 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14629 (recursive-lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14630 '("./lisp/macros.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14631 "./lisp/mail/mailalias.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14632 "./lisp/makesum.el"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14633 @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
14634 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14635 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14636
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14637 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
14638 output we want.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14639
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14640 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
14641
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14642 @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
14643 @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
14644
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14645 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
14646 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
14647 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
14648 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
14649 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
14650 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
14651 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
14652
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14653 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
14654 @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
14655 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
14656 numbers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14657
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14658 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
14659 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
14660 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
14661 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
14662
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14663 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
14664 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
14665 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
14666 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
14667 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
14668 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
14669 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
14670 that we will need.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14671
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14672 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14673 * Sorting:: Sorting lists.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14674 * Files List:: Making a list of files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14675 * Counting function definitions::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14676 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14677
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14678 @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
14679 @subsection Sorting Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14680 @findex sort
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14681
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14682 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
14683 @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
14684 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
14685 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
14686
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14687 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
14688 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
14689 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
14690 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
14691 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
14692 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
14693 alphabetize a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14694
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14695 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14696 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
14697
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14698 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14699 (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
14700 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14701
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14702 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14703 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14704 produces this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14705
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14706 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14707 (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
14708 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14709
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14710 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14711 (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
14712 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
14713 arguments.)
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 Sorting the list returned by the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14716 @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
14717 it uses the @code{<} function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14718
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14719 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14720 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14721 (sort
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14722 (recursive-lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14723 '("../lisp/macros.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14724 "../lisp/mailalias.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14725 "../lisp/makesum.el"))
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
14726 '<)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14727 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14728 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14729
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14730 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14731 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14732 which produces:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14735 (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
14736 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14737
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14738 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14739 (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
14740 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
14741 list that is passed to @code{sort}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14742
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14743 @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
14744 @subsection Making a List of Files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14745
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14746 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
14747 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
14748 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
14749 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
14750 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
14751 recursive call.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14752
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14753 @findex directory-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14754 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
14755 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
14756 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
14757 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
14758 pattern within a single directory.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14759
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14760 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
14761 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
14762 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
14763 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
14764 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
14765 function that descends into the sub-directories.
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 @findex files-in-below-directory
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14768 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
14769 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
14770 @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
14771 @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
14772 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
14773 of sub-directories, but also their attributes.
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 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
14776 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
14777 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
14778
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14779 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14780 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14781 ("../lisp/macros.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14782 "../lisp/mail/rmail.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14783 "../lisp/makesum.el")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14784 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14785 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14786
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14787 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
14788 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
14789 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
14790 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
14791 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
14792 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
14793 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
14794
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14795 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
14796 is @file{abbrev.el}. Its name is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14797 @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
14798 directory or a symbolic link.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14799
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14800 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14801 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
14802 its attributes:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14803
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14804 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14805 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14806 ("/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
14807 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14808 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14809 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14810 100
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14813 (15019 32380)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14814 (14883 48041)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14815 (15214 49336)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14816 11583
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14817 "-rw-rw-r--"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14818 @end group
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 t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14821 341385
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14822 776)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14823 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14824 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14825
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14826 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14827 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
14828 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
14829
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14830 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14831 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14832 ("/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
14833 t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14834 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14835 )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14836 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14837 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14838
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14839 (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
14840 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
14841 @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
14842 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
14843 element.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14844
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14845 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
14846 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
14847 any directories below that directory.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14848
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14849 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
14850 @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
14851 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
14852 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
14853 sub-directory and repeat its actions.
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 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
14856 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
14857 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
14858 @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
14859 @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
14860 @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
14861 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
14862 directory.
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 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
14865 several tasks:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14866
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14867 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14868 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14869 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
14870 @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
14871
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14872 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14873 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
14874 directory; and if so,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14875
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14876 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14877 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14878 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
14879 so skip it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14880
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14881 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14882 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
14883 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14884 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14885
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14886 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
14887 @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
14888 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
14889 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
14890 pattern is `accumulate'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14891 (@pxref{Accumulate, , Recursive Pattern: @emph{accumulate}}),
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14892 using @code{append} as the combiner.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14893
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14894 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14895 (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
14896 (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
14897 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14898
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14899 @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
14900
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14901 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14902 Here is the function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14903
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14904 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14905 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14906 (defun files-in-below-directory (directory)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14907 "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
14908 ;; 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
14909 ;; 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
14910 ;; 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
14911 ;; "/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
14912 (interactive "DDirectory name: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14913 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14914 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14915 (let (el-files-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14916 (current-directory-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14917 (directory-files-and-attributes directory t)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14918 ;; while we are in the current directory
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14919 (while current-directory-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14920 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14921 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14922 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14923 ;; 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
14924 ;; 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
14925 ((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
14926 (setq el-files-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14927 (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
14928 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14929 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14930 ;; 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
14931 ((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
14932 ;; decide whether to skip or recurse
57460
a60664800358 Remove trailing whitespace from file.
Robert J. Chassell <bob@rattlesnake.com>
parents: 57459
diff changeset
14933 (if
57459
dc60b5774fad (files-in-below-directory): remove unneeded `or' expression that looks
Robert J. Chassell <bob@rattlesnake.com>
parents: 57378
diff changeset
14934 (equal "."
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14935 (substring (car (car current-directory-list)) -1))
57459
dc60b5774fad (files-in-below-directory): remove unneeded `or' expression that looks
Robert J. Chassell <bob@rattlesnake.com>
parents: 57378
diff changeset
14936 ;; then do nothing since filename is that of
dc60b5774fad (files-in-below-directory): remove unneeded `or' expression that looks
Robert J. Chassell <bob@rattlesnake.com>
parents: 57378
diff changeset
14937 ;; current directory or parent, "." or ".."
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14938 ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14939 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14940 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14941 ;; 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
14942 (setq el-files-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14943 (append
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14944 (files-in-below-directory
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14945 (car (car current-directory-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14946 el-files-list)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14947 ;; 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
14948 ;; 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
14949 (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
14950 ;; return the filenames
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14951 el-files-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14952 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14953 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14954
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14955 @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
14956
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14957 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
14958 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
14959
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14960 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14961 Thus, on my system,
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 @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
14964 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14965 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14966 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14967 (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
14968 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14969 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14970
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14971 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14972 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
14973 @samp{.el} files.
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 @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
14976 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
14977 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14978
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14979 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14980 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14981 (sort
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14982 (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
14983 'string-lessp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14984 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14985 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14986
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14987 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14988 (defun test ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14989 "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
14990 (insert "\n" (current-time-string) "\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14991 (sit-for 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14992 (sort
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14993 (recursive-lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14994 '("../lisp/macros.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14995 "../lisp/mailalias.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14996 "../lisp/makesum.el"))
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 (insert (format "%s" (current-time-string))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14999
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15000 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15001
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15002 @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
15003 @subsection Counting function definitions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15004
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15005 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
15006 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
15007 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
15008 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
15009
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15010 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
15011 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
15012 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
15013 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
15014 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
15015 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
15016 numbers the @code{top-of-ranges} list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15017
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15018 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15019 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
15020 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
15021 @vindex top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15022
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15023 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15024 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15025 (defvar top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15026 '(10 20 30 40 50
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15027 60 70 80 90 100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15028 110 120 130 140 150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15029 160 170 180 190 200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15030 210 220 230 240 250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15031 260 270 280 290 300)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15032 "List specifying ranges for `defuns-per-range'.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15033 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15034 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15035
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15036 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
15037
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15038 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
15039 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
15040 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
15041 as arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15042
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15043 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
15044 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
15045 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
15046 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
15047 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
15048 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
15049 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
15050 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
15051 top-of-range values in turn.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15052
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15053 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
15054 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
15055 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
15056 small gear inside a big gear.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15057
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15058 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
15059 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
15060 (@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
15061 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
15062 @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
15063 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
15064 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
15065
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15066 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15067 The inner loop looks 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 @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
15072 (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
15073 (setq sorted-lengths (cdr sorted-lengths)))
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 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
15078 @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
15079 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
15080
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15081 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15082 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15083 (while top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15084 @var{body-of-loop}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15085 (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
15086 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15087 @end smallexample
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15090 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
15091
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15092 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15093 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15094 (while top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15095
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15096 ;; @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
15097 (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
15098 (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
15099 (setq sorted-lengths (cdr sorted-lengths)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15101 ;; @r{Move to next range.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15102 (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
15103 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15104 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15105
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15106 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
15107 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
15108 @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
15109 this purpose. (@xref{cons, , @code{cons}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15110
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15111 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
15112 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
15113 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
15114 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
15115 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
15116 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
15117 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
15118 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
15119 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
15120 @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
15121 @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
15122 @findex nreverse
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15123
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15124 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15125 For example,
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15128 (nreverse '(1 2 3 4))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15129 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15130
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15131 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15132 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15133 produces:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15134
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15135 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15136 (4 3 2 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15137 @end smallexample
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 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
15140 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
15141 @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
15142 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
15143 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
15144 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
15145 as is.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15146 @findex reverse
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15149 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
15150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15151 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15152 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15153 (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
15154 "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
15155 (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
15156 (number-within-range 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15157 defuns-per-range-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15158 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15159
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15160 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15161 ;; @r{Outer loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15162 (while top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15163 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15164
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15165 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15166 ;; @r{Inner loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15167 (while (and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15168 ;; @r{Need number for numeric test.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15169 (car sorted-lengths)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15170 (< (car sorted-lengths) top-of-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15171 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15172
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15173 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15174 ;; @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
15175 (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
15176 (setq sorted-lengths (cdr sorted-lengths)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15177
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15178 ;; @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
15179 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15180
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15181 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15182 (setq defuns-per-range-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15183 (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
15184 (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
15185 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15186
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15187 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15188 ;; @r{Move to next range.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15189 (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
15190 ;; @r{Specify next top of range value.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15191 (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
15192 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15193
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15194 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15195 ;; @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
15196 ;; @r{ the largest top-of-range value.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15197 (setq defuns-per-range-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15198 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15199 (length sorted-lengths)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15200 defuns-per-range-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15201 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15204 ;; @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
15205 ;; @r{ smallest to largest.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15206 (nreverse defuns-per-range-list)))
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 1200
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 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
15213 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
15214
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15215 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15216 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15217 (and (car sorted-lengths)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15218 (< (car sorted-lengths) top-of-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15219 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15220 @end smallexample
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15223 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15224 instead of like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15225
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15226 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15227 (< (car sorted-lengths) top-of-range)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15228 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15229
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15230 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
15231 @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
15232 range.
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 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
15235 @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
15236 @code{(car sorted-lengths)} expression function returns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15237 @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
15238 @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
15239 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
15240
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15241 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
15242 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
15243 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
15244 the test will fail.
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 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
15247 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
15248 @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
15249 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
15250 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
15251 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
15252 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
15253 @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
15254 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
15255 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
15256 of the @code{and} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15257
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15258 @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
15259 This way, we avoid an error.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15260 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15261 @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
15262 Functions}, for more information about @code{and}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15263 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15264 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15265 @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
15266 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15267
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15268 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
15269 evaluate the expression that binds (a shortened)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15270 @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
15271 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
15272 evaluate the @code{defuns-per-range} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15273
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15274 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15275 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15276 ;; @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
15277 (setq top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15278 '(110 120 130 140 150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15279 160 170 180 190 200))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15280
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15281 (setq sorted-lengths
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15282 '(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
15283
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15284 (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
15285 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15286 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15287
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15288 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15289 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15290 The list returned looks like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15293 (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
15294 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15295
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15296 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15297 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
15298 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
15299 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
15300 of 200 or larger.
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 @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
15303
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15304 @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
15305 @chapter Readying a Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15306 @cindex Readying a graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15307 @cindex Graph prototype
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15308 @cindex Prototype graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15309 @cindex Body of graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15310
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15311 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
15312 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
15313
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15314 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
15315 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
15316 (@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
15317 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
15318 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
15319 more.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15320
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15321 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
15322 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
15323 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
15324 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
15325 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
15326 the function to label the axes automatically.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15327
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15328 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15329 * Columns of a graph::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15330 * 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
15331 * recursive-graph-body-print::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15332 * Printed Axes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15333 * Line Graph Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15334 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15335
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15336 @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
15337 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15338 @unnumberedsec Printing the Columns of a Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15339 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15340
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15341 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
15342 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
15343 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
15344 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
15345 symbol a user option.
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 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
15348 @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
15349 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
15350
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15351 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
15352 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
15353 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
15354 @code{numbers-list}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15355
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15356 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
15357 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
15358
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15359 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
15360 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
15361 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
15362 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
15363
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15364 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
15365 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
15366 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
15367 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
15368 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
15369 @findex apropos
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 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
15372 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
15373 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
15374 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
15375 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
15376 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
15377 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
15378 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
15379
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15380 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15381 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
15382
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15383 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15384 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15385 insert-rectangle:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15386 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
15387 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
15388 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
15389 RECTANGLE should be a list of strings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15390 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15391 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15392
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15393 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
15394
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15395 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
15396 @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
15397 (@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
15398 @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
15399 point. Also the function returns @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15400
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15401 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15402 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15403 (insert-rectangle '("first" "second" "third"))first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15404 second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15405 third
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15406 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15407 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15408 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15409
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15410 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15411 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
15412 @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
15413 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
15414 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
15415 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
15416 column of strings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15417
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15418 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
15419 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
15420 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
15421 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
15422 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
15423 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
15424 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
15425 is the keybinding for @code{eval-expression}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15426
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15427 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
15428 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
15429 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
15430 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
15431 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
15432 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
15433
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15434 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
15435 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
15436 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
15437 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
15438 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
15439 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
15440 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
15441 right---or perhaps we can@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15442
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15443 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
15444 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
15445 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
15446 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
15447 @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
15448 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
15449 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
15450 be difficult.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15451
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15452 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
15453 @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
15454 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
15455 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
15456 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
15457 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
15458 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
15459 @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
15460
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15461 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15462 (" " " " "*" "*" "*")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15463 @end smallexample
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 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
15466 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
15467 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
15468 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
15469 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
15470 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
15471 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
15472 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
15473 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
15474 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
15475 example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15476
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15477 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15478 (max 3 4 6 5 7 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15479 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15480
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15481 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15482 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
15483 smallest of all its arguments.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15484 @findex max
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15485 @findex min
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 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
15488 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
15489 numbers. Thus, the following expression,
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15492 (max '(3 4 6 5 7 3))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15493 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15494
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15495 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15496 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15497 produces the following error message;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15498
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15499 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15500 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
15501 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15502
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15503 @findex apply
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15504 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
15505 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
15506 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
15507 may be a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15508
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15509 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15510 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15511
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15512 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15513 (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
15514 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15515
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15516 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15517 returns 8.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15518
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15519 (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
15520 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
15521 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
15522 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
15523 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
15524 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
15525 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
15526 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
15527 it.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15528
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15529 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
15530 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
15531 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
15532
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15533 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15534 (apply 'max '(4 8 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15535 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15536
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15537 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
15538 @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
15539 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
15540 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
15541 sorted or not.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15542
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15543 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15544 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
15545
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15546 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15547 (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
15548 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15549
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15550 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
15551 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
15552 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
15553 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
15554 @code{insert-rectangle} command to insert.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15555
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15556 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
15557 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
15558 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
15559 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
15560 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
15561 @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
15562
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15563 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15564 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15565 ;;; @r{First version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15566 (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
15567 "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
15568 (let ((insert-list nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15569 (number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15570 (- max-graph-height actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15571 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15572
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15573 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15574 ;; @r{Fill in asterisks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15575 (while (> actual-height 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15576 (setq insert-list (cons "*" insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15577 (setq actual-height (1- actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15578 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15579
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15580 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15581 ;; @r{Fill in blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15582 (while (> number-of-top-blanks 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15583 (setq insert-list (cons " " insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15584 (setq number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15585 (1- number-of-top-blanks)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15586 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15587
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15588 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15589 ;; @r{Return whole list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15590 insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15591 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15592 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15593
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15594 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
15595 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
15596
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15597 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15598 (column-of-graph 5 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15599 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15600
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15601 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15602 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15603 returns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15604
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15605 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15606 (" " " " "*" "*" "*")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15607 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15608
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15609 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
15610 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
15611 `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
15612 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
15613 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
15614 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
15615 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
15616 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
15617 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
15618 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
15619 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
15620 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
15621 those variables separately.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15622
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15623 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
15624 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
15625
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15626 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15627 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15628 (defvar graph-symbol "*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15629 "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
15630 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15633 (defvar graph-blank " "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15634 "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
15635 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
15636 as graph-symbol.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15637 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15638 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15639
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15640 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15641 (For an explanation of @code{defvar}, see
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15642 @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
15643
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15644 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15645 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15646 ;;; @r{Second version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15647 (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
15648 "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
15649
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15652 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
15653 of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15654 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
15655 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
15656 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15657
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15658 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15659 (let ((insert-list nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15660 (number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15661 (- max-graph-height actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15662 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15663
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15664 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15665 ;; @r{Fill in @code{graph-symbols}.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15666 (while (> actual-height 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15667 (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
15668 (setq actual-height (1- actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15669 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15672 ;; @r{Fill in @code{graph-blanks}.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15673 (while (> number-of-top-blanks 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15674 (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
15675 (setq number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15676 (1- number-of-top-blanks)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15677
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15678 ;; @r{Return whole list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15679 insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15680 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15681 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15682
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15683 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
15684 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
15685 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
15686 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
15687 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
15688 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
15689 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
15690 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
15691 the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15692
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15693 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
15694 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
15695 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
15696 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
15697 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
15698 simple.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15699
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15700 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
15701 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
15702 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
15703
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15704 @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
15705 @section The @code{graph-body-print} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15706 @findex graph-body-print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15707
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15708 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
15709 @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
15710 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
15711 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
15712 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
15713 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
15714 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
15715
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15716 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
15717 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
15718
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15719 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
15720 version of this function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15721
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15722 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15723 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15724 (defun graph-body-print (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15725 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15726 (let ((height @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15727 @dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15728 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15729
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15730 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15731 (while numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15732 @var{insert-columns-and-reposition-point}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15733 (setq numbers-list (cdr numbers-list)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15734 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15735 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15736
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15737 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15738 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
15739
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15740 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
15741 determine the height of the graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15742
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15743 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
15744 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
15745 (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
15746 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
15747
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15748 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
15749 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
15750 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
15751 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
15752 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
15753 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
15754 from which @code{insert-rectangle} is called.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15755
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15756 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
15757 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
15758 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
15759 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
15760 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
15761 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
15762 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
15763 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
15764 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
15765
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15766 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15767 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
15768
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15769 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15770 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15771 (defun graph-body-print (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15772 "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
15773 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
15774
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15775 (let ((height (apply 'max numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15776 (symbol-width (length graph-blank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15777 from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15778 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15779
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15780 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15781 (while numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15782 (setq from-position (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15783 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15784 (column-of-graph height (car numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15785 (goto-char from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15786 (forward-char symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15787 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15788 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15789 ;; @r{Draw graph column by column.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15790 (sit-for 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15791 (setq numbers-list (cdr numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15792 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15793 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15794 ;; @r{Place point for X axis labels.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15795 (forward-line height)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15796 (insert "\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15797 ))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15798 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15799 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15802 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
15803 @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
15804 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
15805 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
15806 `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
15807 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
15808 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
15809 function exits.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15810
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15811 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
15812
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15813 @enumerate
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 Install @code{graph-symbol}, @code{graph-blank},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15816 @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
15817 @iftex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
15818 @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
15819 @end iftex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
15820 @ifinfo
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
15821 @ref{Columns of a graph},
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
15822 @end ifinfo
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15823 and @code{graph-body-print}.
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15826 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15827 Copy the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15828
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15829 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15830 (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
15831 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15832
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15833 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15834 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
15835 want the graph to start.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15836
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15837 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15838 Type @kbd{M-:} (@code{eval-expression}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15839
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15840 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15841 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
15842 with @kbd{C-y} (@code{yank)}.
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15845 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
15846 @end enumerate
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15849 Emacs will print a graph like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15852 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15853 *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15854 * **
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15855 * ****
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15856 *** ****
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15857 ********* *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15858 ************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15859 *************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15860 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15861 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15862
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15863 @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
15864 @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
15865 @findex recursive-graph-body-print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15866
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15867 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
15868 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
15869 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
15870 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
15871 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
15872 the graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15873
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15874 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15875 The `wrapper' is uncomplicated:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15876
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15877 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15878 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15879 (defun recursive-graph-body-print (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15880 "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
15881 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
15882 (let ((height (apply 'max numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15883 (symbol-width (length graph-blank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15884 from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15885 (recursive-graph-body-print-internal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15886 numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15887 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15888 symbol-width)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15889 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15890 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15891
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15892 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
15893 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
15894 `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
15895 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
15896 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
15897 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
15898 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
15899 `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
15900 version of the @code{numbers-list}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15901
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15902 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15903 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15904 (defun recursive-graph-body-print-internal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15905 (numbers-list height symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15906 "Print a bar graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15907 Used within recursive-graph-body-print function."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15908 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15909
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15910 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15911 (if numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15912 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15913 (setq from-position (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15914 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15915 (column-of-graph height (car numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15916 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15917 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15918 (goto-char from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15919 (forward-char symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15920 (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
15921 (recursive-graph-body-print-internal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15922 (cdr numbers-list) height symbol-width))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15923 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15924 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15925
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15926 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15927 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
15928
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15929 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15930 (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
15931 @end smallexample
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15934 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
15935
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15936 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15937 @group
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 ** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15940 **** *
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 * *********
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15943 ************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15944 *************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15945 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15946 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15947
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15948 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
15949 @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
15950
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15951 @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
15952 @section Need for Printed Axes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15953
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15954 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
15955 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
15956 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
15957
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15958 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
15959 @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
15960 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
15961 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
15962 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
15963
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15964 @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
15965 @section Exercise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15966
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15967 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
15968
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15969 @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
15970 @chapter Your @file{.emacs} File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15971 @cindex @file{.emacs} file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15972 @cindex Customizing your @file{.emacs} file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15973 @cindex Initialization file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15974
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15975 ``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
15976 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
15977 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
15978 it to suit themselves.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15979
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15980 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
15981 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
15982
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15983 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15984 * Default Configuration::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15985 * 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
15986 * defcustom:: Emacs will write code for you.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15987 * 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
15988 * Text and Auto-fill:: Automatically wrap lines.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15989 * Mail Aliases:: Use abbreviations for email addresses.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15990 * 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
15991 * Keybindings:: Create some personal keybindings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15992 * Keymaps:: More about key binding.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15993 * 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
15994 * Autoload:: Make functions available.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15995 * 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
15996 * 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
15997 * Miscellaneous::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15998 * 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
15999 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16001 @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
16002 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16003 @unnumberedsec Emacs' Default Configuration
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16004 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16005
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16006 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
16007 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
16008 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
16009 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
16010 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
16011 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
16012 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
16013 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
16014 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
16015
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16016 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
16017 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
16018 customize Emacs: so it suits me.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16019
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16020 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
16021 @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
16022 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
16023 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
16024 @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
16025 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
16026 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
16027 naming conventions; the old format saves typing.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16028
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16029 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
16030 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
16031 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
16032 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
16033
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16034 (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
16035 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
16036 @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
16037
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16038 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
16039 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
16040 @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
16041 @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
16042 Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16043
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16044 @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
16045 @section Site-wide Initialization Files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16046
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16047 @cindex @file{default.el} init file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16048 @cindex @file{site-init.el} init file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16049 @cindex @file{site-load.el} init file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16050 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
16051 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
16052 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
16053 everyone.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16054
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16055 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
16056 @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
16057 `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
16058 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
16059 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
16060 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
16061 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
16062 @file{INSTALL} file.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16063
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16064 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
16065 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
16066 @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
16067 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
16068 loaded @emph{after} your @file{.emacs} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16069
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16070 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
16071 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
16072 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
16073 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
16074 (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
16075 @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
16076 Simple Extension}.)
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 @c Rewritten to avoid overfull hbox.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16079 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
16080 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
16081
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16082 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
16083 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
16084 Emacs distribution and are worth perusing.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16085
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16086 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
16087 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
16088 initialization file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16089
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16090 @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
16091 @section Specifying Variables using @code{defcustom}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16092 @findex defcustom
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 specify variables using @code{defcustom} so that you and
44899
ebddb2618c17 Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 43431
diff changeset
16095 others can then use Emacs' @code{customize} feature to set their
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16096 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
16097 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
16098 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
16099 file.)
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 @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
16102 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
16103 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
16104 job.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16105
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16106 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
16107 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
16108 @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
16109 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
16110 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
16111 documentation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16112
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16113 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
16114 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
16115 arguments are optional.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16116
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16117 Each of these arguments consists of a keyword followed by a value.
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
16118 Each keyword starts with the colon character @samp{:}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16119
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16120 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16121 For example, the customizable user option variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16122 @code{text-mode-hook} looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16123
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16124 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16125 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16126 (defcustom text-mode-hook nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16127 "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
16128 :type 'hook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16129 :options '(turn-on-auto-fill flyspell-mode)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16130 :group 'data)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16131 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16132 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16133
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16134 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16135 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
16136 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
16137
53099
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
16138 The @code{:type} keyword tells Emacs the kind of data to which
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
16139 @code{text-mode-hook} should be set and how to display the value in a
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
16140 Customization buffer.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16141
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16142 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
16143 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
16144 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
16145 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
16146 @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
16147 user.
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 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
16150 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
16151 find it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16152
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16153 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
16154 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
16155
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16156 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
16157
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16158 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
16159 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
16160
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16161 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16162 Using the customization command, you can type:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16163
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16164 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16165 M-x customize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16166 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16167
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16168 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16169 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
16170 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
16171 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
16172 button to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16173
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16174 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16175 Save for Future Sessions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16176 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16177
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16178 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16179 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
16180 It will look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16181
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16182 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16183 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16184 (custom-set-variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16185 ;; custom-set-variables was added by Custom --
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16186 ;; don't edit or cut/paste it!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16187 ;; 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
16188 '(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
16189 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16190 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16191
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16192 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16193 (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
16194 @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
16195
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16196 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
16197 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
16198 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
16199 inadvertently generate an error.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16200
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
16201 The @code{custom-set-variables} function works somewhat differently
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
16202 than a @code{setq}. While I have never learned the differences, I do
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
16203 modify the @code{custom-set-variables} expressions in my @file{.emacs}
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
16204 file by hand: I make the changes in what appears to me to be a
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
16205 reasonable manner and have not had any problems. Others prefer to use
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
16206 the Customization command and let Emacs do the work for them.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16207
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16208 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
16209 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
16210 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
16211 @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
16212 @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
16213
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16214 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
16215 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
16216 with the @code{custom-set-@dots{}} functions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16217
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16218 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16219 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
16220 message that says
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16221
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16222 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16223 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
16224 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16225
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16226 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16227 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
16228
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16229 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16230 Save for Future Sessions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16231 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16234 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
16235 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
16236 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
16237 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
16238 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
16239 forget, you may confuse yourself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16240
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16241 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
16242 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
16243 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
16244
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16245 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
16246 expressions myself.
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 @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
16249 @section Beginning a @file{.emacs} File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16250 @cindex @file{.emacs} file, beginning of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16251
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16252 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
16253 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
16254 @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
16255
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16256 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
16257 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
16258 definitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16259
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16260 @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
16261 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
16262
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16263 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
16264 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
16265
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16266 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
16267 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
16268 not.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16269
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
16270 @need 1200
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16271 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16272 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16273 ;;;; Bob's .emacs file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16274 ; Robert J. Chassell
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16275 ; 26 September 1985
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 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
16281 adding to it ever since.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16282
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16283 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16284 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16285 ; 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
16286 ; line beginning with four semicolons; and each
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16287 ; 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
16288 ; three semicolons.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16289 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16290 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16291
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16292 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16293 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
16294 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
16295 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
16296 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
16297 Manual}, for more about comments.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16298
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16299 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16300 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16301 ;;;; The Help Key
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16302 ; Control-h is the help key;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16303 ; 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
16304 ; 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
16305 ; For an explanation of the help facility,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16306 ; 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
16307 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16308 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16309
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16310 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16311 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
16312
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16313 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16314 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16315 ; 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
16316 ; 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
16317 ; 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
16318 ; control-h m.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16319 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16320 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16321
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16322 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16323 `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
16324 all you need to know.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16325
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16326 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
16327 @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
16328 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
16329 remember to look here to remind myself.
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 @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
16332 @section Text and Auto Fill Mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16333
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16334 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
16335 Auto Fill mode.
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16338 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16339 ;;; Text mode and Auto Fill mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16340 ; 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
16341 ; 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
16342 ; 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
16343
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16344 (setq default-major-mode 'text-mode)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16345 (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
16346 (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
16347 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16348 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16349
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16350 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
16351 besides remind a forgetful human!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16352
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16353 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
16354 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
16355 other mode, such as C mode.
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 @cindex Per-buffer, local variables list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16358 @cindex Local variables list, per-buffer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16359 @cindex Automatic mode selection
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16360 @cindex Mode selection, automatic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16361 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
16362 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
16363 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
16364 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
16365 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
16366 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
16367 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
16368 per-buffer, ``local variables list'', if any.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16369
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16370 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16371 @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
16372 Emacs Manual}.
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 @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
16375 Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16376 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16377 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16378 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
16379 Files'' in @cite{The GNU Emacs Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16380 @end iftex
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 Now, back to the @file{.emacs} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16383
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16384 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16385 Here 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
16386
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16387 @cindex Text Mode turned on
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16388 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16389 (setq default-major-mode 'text-mode)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16390 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16393 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
16394
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16395 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
16396 @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
16397 @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
16398 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
16399 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
16400 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
16401 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
16402 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
16403 else in Emacs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16404
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16405 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16406 Here are the next two lines:
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 @cindex Auto Fill mode turned on
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16409 @findex add-hook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16410 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16411 (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
16412 (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
16413 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16414
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16415 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16416 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
16417 @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
16418 @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
16419 variable.
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 @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
16422 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
16423 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
16424 are in Text mode.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16425
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16426 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
16427 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
16428 turns on Auto Fill mode.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16429
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16430 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
16431 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
16432 variables tell Emacs otherwise.
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 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
16435 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
16436 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
16437 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
16438 @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
16439 the @samp{t} of @samp{it's}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16440
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16441 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
16442 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
16443 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
16444 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
16445 within them.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16446
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16447 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
16448 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
16449 @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
16450 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
16451 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
16452
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16453 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16454 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
16455 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
16456
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16457 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16458 (setq colon-double-space t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16459 @end smallexample
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 @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
16462 @section Mail Aliases
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16463
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16464 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
16465 reminders.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16466
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16467 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16468 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16469 ;;; Mail mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16470 ; 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
16471 ; To enter RMAIL (for reading mail),
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16472 ; type `M-x rmail'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16473
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16474 (setq mail-aliases t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16475 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16476 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16477
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16478 @cindex Mail aliases
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 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
16481 @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
16482 says, in effect, ``Yes, use mail aliases.''
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16483
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16484 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
16485 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
16486 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
16487
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16488 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16489 alias geo george@@foobar.wiz.edu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16490 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16491
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16492 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16493 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
16494 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
16495
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16496 @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
16497 @section Indent Tabs Mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16498 @cindex Tabs, preventing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16499 @findex indent-tabs-mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16501 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
16502 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
16503 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
16504 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
16505 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
16506
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16507 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16508 The following turns off Indent Tabs mode:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16509
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16510 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16511 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16512 ;;; Prevent Extraneous Tabs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16513 (setq-default indent-tabs-mode nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16514 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16515 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16516
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16517 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
16518 @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
16519 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
16520 values for the variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16521
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16522 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16523 @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
16524
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16525 @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
16526 Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16527 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16528 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16529 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
16530 Files'' in @cite{The GNU Emacs Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16531 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16532
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16533 @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
16534 @section Some Keybindings
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16535
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16536 Now for some personal keybindings:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16539 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16540 ;;; Compare windows
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16541 (global-set-key "\C-cw" 'compare-windows)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16542 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16543 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16544
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16545 @findex compare-windows
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16546 @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
16547 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
16548 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
16549 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
16550
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16551 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
16552
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16553 @cindex Setting a key globally
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16554 @cindex Global set key
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16555 @cindex Key setting globally
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16556 @findex global-set-key
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16557 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
16558 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
16559 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
16560 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
16561 `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
16562 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
16563 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
16564 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
16565 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
16566 Manual}, for details.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16567
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16568 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
16569 @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
16570 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
16571
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16572 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
16573 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
16574 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
16575 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
16576 adapt what is there.
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 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
16579 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
16580 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
16581 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
16582 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
16583 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
16584 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
16585 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
16586 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
16587
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16588 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16589 Here is another keybinding, with a comment:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16590
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16591 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16592 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16593 ;;; Keybinding for `occur'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16594 ; 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
16595 (global-set-key "\C-co" 'occur)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16596 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16597 @end smallexample
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 @findex occur
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16600 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
16601 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
16602 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
16603 to jump to occurrences.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16604
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16605 @findex global-unset-key
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16606 @cindex Unbinding key
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16607 @cindex Key unbinding
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16608 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16609 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
16610 work:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16613 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16614 ;;; Unbind `C-x f'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16615 (global-unset-key "\C-xf")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16616 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16617 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16618
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16619 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
16620 @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
16621 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
16622 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
16623 default width, I simply unbound the key.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16624
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16625 @findex list-buffers, @r{rebound}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16626 @findex buffer-menu, @r{bound to key}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16627 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16628 The following rebinds an existing key:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16629
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16630 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16631 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16632 ;;; 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
16633 (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
16634 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16635 @end smallexample
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 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
16638 @code{list-buffers} command. This command lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16639 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
16640 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
16641 window, I prefer the @code{buffer-menu}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16642 command, which not only lists the buffers,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16643 but moves point into that window.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16644
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16645 @node Keymaps, Loading Files, Keybindings, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16646 @section Keymaps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16647 @cindex Keymaps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16648 @cindex Rebinding keys
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 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
16651 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
16652 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
16653 @code{current-global-map}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16654
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16655 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
16656 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
16657 all buffers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16658
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16659 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
16660 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
16661 function @code{buffer-menu}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16662
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16663 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16664 (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
16665 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16666
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16667 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
16668 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
16669 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
16670 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
16671 to @kbd{C-c C-c g}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16672
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16673 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16674 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16675 (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
16676 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16677 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16678
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16679 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16680 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
16681 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
16682 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
16683 @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
16684 (@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
16685 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
16686 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
16687
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16688 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16689 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
16690
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16691 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16692 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16693 (defun texinfo-insert-@@group ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16694 "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
16695 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16696 (beginning-of-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16697 (insert "@@group\n"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16698 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16699 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16700
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16701 (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
16702 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
16703 with other Texinfo mode key bindings.)
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 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
16706 @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
16707 @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
16708
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16709 @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
16710 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
16711 Reference Manual}, for more information about keymaps.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16712
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16713 @node Loading Files, Autoload, Keymaps, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16714 @section Loading Files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16715 @cindex Loading files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16716 @c findex load
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 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
16719 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
16720 releases. For example, the Calendar and Diary packages are now part
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
16721 of the standard GNU Emacs, as is Calc.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16722
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16723 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
16724 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
16725 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16726
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16727 @c (auto-compression-mode t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16728
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16729 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16730 (load "~/emacs/slowsplit")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16731 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16732
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16733 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
16734 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
16735 @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
16736 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
16737 1989.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16738
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16739 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
16740 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
16741 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
16742 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
16743 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
16744 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
16745 window.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16746
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16747 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16748 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
16749 @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
16750 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
16751
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16752 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16753 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16754 (global-unset-key "\C-x2")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16755 (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
16756 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16757 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16758
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16759 @vindex load-path
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16760 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
16761 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
16762 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
16763 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
16764 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
16765 when Emacs is built.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16766
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16767 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16768 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
16769 existing load path:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16770
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16771 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16772 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16773 ;;; Emacs Load Path
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16774 (setq load-path (cons "~/emacs" load-path))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16775 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16776 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16777
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16778 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
16779 @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
16780
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16781 @findex load-library
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16782 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16783 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16784 (defun load-library (library)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16785 "Load the library named LIBRARY.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16786 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
16787 (interactive "sLoad library: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16788 (load library))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16789 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16790 @end smallexample
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 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
16793 `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
16794 @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
16795
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16796 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
16797 @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
16798 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
16799 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
16800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16801 @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
16802 @section Autoloading
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16803 @findex autoload
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16804
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16805 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
16806 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
16807 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
16808 is called @dfn{autoloading}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16809
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16810 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
16811 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
16812
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16813 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
16814 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
16815 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
16816
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16817 Rarely used functions are frequently autoloaded. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16818 @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
16819 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
16820 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
16821 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
16822 @file{.emacs} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16823
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16824 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
16825 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
16826 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
16827 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
16828 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
16829 file for more about dumping.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16830
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16831 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
16832 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
16833 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
16834 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
16835 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
16836 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
16837 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
16838 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
16839 function (the default is a function).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16840
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16841 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16842 Here is a typical example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16843
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16844 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16845 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16846 (autoload 'html-helper-mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16847 "html-helper-mode" "Edit HTML documents" t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16848 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16849 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16850
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16851 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16852 (@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
16853 is a standard part of the distribution).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16854
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16855 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16856 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
16857 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
16858 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
16859 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
16860 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
16861 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
16862 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
16863 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
16864 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
16865 documentation is not available.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16866
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16867 @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
16868 Manual}, for more information.
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 @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
16871 @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
16872 @findex line-to-top-of-window
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16873 @cindex Simple extension in @file{.emacs} file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16874
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16875 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
16876 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
16877 to read.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16878
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16879 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
16880 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
16881 @file{.emacs} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16882
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16883 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16884 Here is the definition:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16885
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16886 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16887 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16888 ;;; Line to top of window;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16889 ;;; 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
16890 (defun line-to-top-of-window ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16891 "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
16892 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16893 (recenter 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16894 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16895 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16896
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16897 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16898 Now for the keybinding.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16899
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16900 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
16901 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
16902 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
16903 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
16904
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16905 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
16906 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16907
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16908 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16909 (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
16910 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16911
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16912 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
16913 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
16914
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16915 @cindex Conditional 'twixt two versions of Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16916 @cindex Version of Emacs, choosing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16917 @cindex Emacs version, choosing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16918 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
16919 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
16920 the following conditional:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16921
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16922 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16923 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16924 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16925 ((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
16926 ;; evaluate version 20 code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16927 ( @dots{} ))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16928 ((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
16929 ;; evaluate version 21 code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16930 ( @dots{} )))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16931 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16932 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16933
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16934 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
16935 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
16936 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
16937 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
16938 @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
16939
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16940 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16941 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
16942 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16943 }:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16944
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16945 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16946 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16947 (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
16948 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16949 (blink-cursor-mode 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16950 ;; 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
16951 ;; at the end of the buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16952 (setq next-line-add-newlines t)
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 on image viewing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16956 (auto-image-file-mode t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16957 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16958 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16959 ;; 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
16960 ;; (Use numeric argument to turn on)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16961 (menu-bar-mode 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16962 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16963 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16964 ;; 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
16965 ;; (Use numeric argument to turn on)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16966 (tool-bar-mode nil)
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16969 ;; Turn off tooltip mode for tool bar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16970 ;; (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
16971 ;; (Use numeric argument to turn on)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16972 (tooltip-mode nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16973 ;; 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
16974 (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
16975 ))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16976 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16977 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16980 (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
16981 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
16982 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
16983 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
16984 @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
16985 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
16986 @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
16987
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16988 @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
16989 @section X11 Colors
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 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
16992 system.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16993
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16994 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
16995
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16996 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16997 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
16998 file that set values:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16999
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17000 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17001 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17002 ;; Set cursor color
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17003 (set-cursor-color "white")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17004
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17005 ;; Set mouse color
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17006 (set-mouse-color "white")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17007
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17008 ;; Set foreground and background
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17009 (set-foreground-color "white")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17010 (set-background-color "darkblue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17011 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17012
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17013 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17014 ;;; Set highlighting colors for isearch and drag
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17015 (set-face-foreground 'highlight "white")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17016 (set-face-background 'highlight "blue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17017 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17018
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17019 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17020 (set-face-foreground 'region "cyan")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17021 (set-face-background 'region "blue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17022 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17023
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17024 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17025 (set-face-foreground 'secondary-selection "skyblue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17026 (set-face-background 'secondary-selection "darkblue")
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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17029 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17030 ;; Set calendar highlighting colors
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17031 (setq calendar-load-hook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17032 '(lambda ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17033 (set-face-foreground 'diary-face "skyblue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17034 (set-face-background 'holiday-face "slate blue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17035 (set-face-foreground 'holiday-face "white")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17036 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17037 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17038
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17039 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
17040 the screen flicker.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17041
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17042 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
17043 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
17044 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
17045 @file{~/.Xresources} file like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17048 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17049 Emacs*foreground: white
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17050 Emacs*background: darkblue
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17051 Emacs*cursorColor: white
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17052 Emacs*pointerColor: white
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17053 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17054 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17055
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17056 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
17057 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
17058 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
17059 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
17060 image rather than a plain color.}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17061
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17062 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17063 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17064 # I use TWM for window manager.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17065 xsetroot -solid Navy -fg white &
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17066 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17067 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17068
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17069 @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
17070 @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
17071
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17072 Here are a few miscellaneous settings:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17073 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17074
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17075 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17076 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17077 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
17078 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17079 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17080 ; Cursor shapes are defined in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17081 ; `/usr/include/X11/cursorfont.h';
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17082 ; 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
17083 ; 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
17084 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17085
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17086 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17087 (let ((mpointer (x-get-resource "*mpointer"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17088 "*emacs*mpointer")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17089 ;; 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
17090 ;; then set it, otherwise leave as is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17091 (if (eq mpointer nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17092 (setq mpointer "132")) ; top_left_arrow
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17093 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17094 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17095 (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
17096 (set-mouse-color "white"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17097 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17098 @end smallexample
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17099
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17100 @item
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17101 Convert @kbd{@key{CTL}-h} into @key{DEL} and @key{DEL}
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17102 into @kbd{@key{CTL}-h}.@*
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17103 (Some olders keyboards needed this, although I have not seen the
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17104 problem recently.)
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17105
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17106 @smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17107 @group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17108 ;; Translate `C-h' to <DEL>.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17109 ; (keyboard-translate ?\C-h ?\C-?)
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17110
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17111 ;; Translate <DEL> to `C-h'.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17112 (keyboard-translate ?\C-? ?\C-h)
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17113 @end group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17114 @end smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17115
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17116 @item Turn off a blinking cursor!
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17117
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17118 @smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17119 @group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17120 (if (fboundp 'blink-cursor-mode)
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17121 (blink-cursor-mode -1))
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17122 @end group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17123 @end smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17124
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17125 @item Ignore case when using `grep'@*
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17126 @samp{-n}@w{ } Prefix each line of output with line number@*
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17127 @samp{-i}@w{ } Ignore case distinctions@*
57460
a60664800358 Remove trailing whitespace from file.
Robert J. Chassell <bob@rattlesnake.com>
parents: 57459
diff changeset
17128 @samp{-e}@w{ } Protect patterns beginning with a hyphen character, @samp{-}
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17129
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17130 @smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17131 (setq grep-command "grep -n -i -e ")
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17132 @end smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17133
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17134 @item Automatically uncompress compressed files when visiting them
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17135
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17136 @smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17137 (load "uncompress")
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17138 @end smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17139
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17140 @item Find an existing buffer, even if it has a different name@*
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17141 This avoids problems with symbolic links.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17142
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17143 @smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17144 (setq find-file-existing-other-name t)
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17145 @end smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17146
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17147 @item Set your language environment and default input method
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17148
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17149 @smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17150 @group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17151 (set-language-environment "latin-1")
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17152 ;; Remember you can enable or disable multilingual text input
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17153 ;; with the @code{toggle-input-method'} (@kbd{C-\}) command
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17154 (setq default-input-method "latin-1-prefix")
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17155 @end group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17156 @end smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17157
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17158 If you want to write with Chinese `GB' characters, set this instead:
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17159
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17160 @smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17161 @group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17162 (set-language-environment "Chinese-GB")
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17163 (setq default-input-method "chinese-tonepy")
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17164 @end group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17165 @end smallexample
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17166 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17167
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17168 @subsubheading Fixing Unpleasant Key Bindings
57460
a60664800358 Remove trailing whitespace from file.
Robert J. Chassell <bob@rattlesnake.com>
parents: 57459
diff changeset
17169 @cindex Key bindings, fixing
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17170 @cindex Bindings, key, fixing unpleasant
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17171
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17172 Some systems bind keys unpleasantly. Sometimes, for example, the
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17173 @key{CTL} key appears in an awkward spot rather than at the far left
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17174 of the home row.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17175
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17176 Usually, when people fix these sorts of keybindings, they do not
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17177 change their @file{~/.emacs} file. Instead, they bind the proper keys
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17178 on their consoles with the @code{loadkeys} or @code{install-keymap}
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17179 commands in their boot script and then include @code{xmodmap} commands
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17180 in their @file{.xinitrc} or @file{.Xsession} file for X Windows.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17181
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17182 @need 1250
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17183 @noindent
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17184 For a boot script:
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17185
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17186 @smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17187 @group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17188 loadkeys /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17189
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17190 @exdent or
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17191
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17192 install-keymap emacs2
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17193 @end group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17194 @end smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17195
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17196 @need 1250
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17197 @noindent
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17198 For a @file{.xinitrc} or @file{.Xsession} file when the @key{Caps
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17199 Lock} key is at the far left of the home row:
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17200
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17201 @smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17202 @group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17203 # Bind the key labeled `Caps Lock' to `Control'
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17204 # (Such a broken user interface suggests that keyboard manufacturers
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17205 # think that computers are typewriters from 1885.)
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17206
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17207 xmodmap -e "clear Lock"
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17208 xmodmap -e "add Control = Caps_Lock"
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17209 @end group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17210 @end smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17211
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17212 @need 1250
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17213 @noindent
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17214 In a @file{.xinitrc} or @file{.Xsession} file, to convert an @key{ALT}
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17215 key to a @key{META} key:
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17216
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17217 @smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17218 @group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17219 # Some ill designed keyboards have a key labeled ALT and no Meta
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17220 xmodmap -e "keysym Alt_L = Meta_L Alt_L"
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17221 @end group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17222 @end smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17223
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17224 @node Mode Line, , Miscellaneous, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17225 @section A Modified Mode Line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17226 @vindex default-mode-line-format
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17227 @cindex Mode line format
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17228
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17229 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
17230
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17231 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
17232 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
17233
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17234 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
17235
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17236 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17237 -:-- 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
17238 @end smallexample
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 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
17241 @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
17242 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
17243
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17244 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17245 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
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17249 ;; 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
17250 ;; 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
17251 (setq default-mode-line-format
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17252 (quote
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17253 (#("-" 0 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17254 (help-echo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17255 "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
17256 mode-line-mule-info
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17257 mode-line-modified
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17258 mode-line-frame-identification
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 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17261 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17262 mode-line-buffer-identification
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 (:eval (substring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17265 (system-name) 0 (string-match "\\..+" (system-name))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17266 ":"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17267 default-directory
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17268 #(" " 0 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17269 (help-echo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17270 "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
17271 (line-number-mode " Line %l ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17272 global-mode-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17273 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17274 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17275 #(" %[(" 0 6
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17276 (help-echo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17277 "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
17278 (:eval (mode-line-mode-name))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17279 mode-line-process
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17280 minor-mode-alist
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17281 #("%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
17282 ")%] "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17283 (-3 . "%P")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17284 ;; "-%-"
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 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17287 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17290 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
17291 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
17292 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
17293 it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17294
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17295 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
17296 @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
17297 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
17298 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
17299 have not discussed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17300
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17301 @cindex Properties, in mode line example
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17302 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
17303 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
17304 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
17305 or, as in this case, a help feature. If you place your mouse cursor
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17306 over the hyphen, some help information appears (By default, you must
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17307 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
17308 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
17309
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17310 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17311 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
17312
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17313 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17314 #("-" 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
17315 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17316
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17317 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17318 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
17319 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
17320 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
17321 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
17322 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
17323 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
17324 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
17325 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
17326 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
17327 string format can be repeated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17328
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17329 @xref{Text Properties, , Text Properties, elisp, The GNU Emacs Lisp
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17330 Reference Manual}, and see @ref{Mode Line Format, , Mode Line Format,
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17331 elisp, The GNU Emacs Lisp Reference Manual}, for more information.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17332
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17333 @code{mode-line-buffer-identification}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17334 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
17335 beginning @code{(#("%12b" 0 4 @dots{}}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17336 The @code{#(} begins the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17337
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17338 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
17339 @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
17340 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
17341 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
17342 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
17343 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
17344 window.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17345
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17346 @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
17347 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
17348 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
17349 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
17350 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
17351 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
17352 length is the name of the machine.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17353
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17354 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17355 This is the expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17356
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17357 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17358 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17359 (:eval (substring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17360 (system-name) 0 (string-match "\\..+" (system-name))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17361 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17362 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17363
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17364 @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
17365 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
17366 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
17367 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
17368 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
17369 @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
17370 out the line.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17371
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17372 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
17373 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
17374 keys than a default Emacs.
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 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
17377 Emacs, with no customization, type:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17378
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17379 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17380 emacs -q
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17381 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17382
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17383 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17384 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
17385 @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
17386 more.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17387
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17388 @node Debugging, Conclusion, Emacs Initialization, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17389 @chapter Debugging
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17390 @cindex debugging
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17391
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17392 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
17393 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
17394 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
17395
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17396 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
17397 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
17398 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
17399
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17400 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17401 * 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
17402 * 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
17403 * 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
17404 * 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
17405 * Debugging Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17406 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17407
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17408 @node debug, debug-on-entry, Debugging, Debugging
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17409 @section @code{debug}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17410 @findex debug
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17411
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17412 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
17413 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
17414 @code{triangle} function discussed earlier. @xref{Decrementing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17415 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
17416 @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
17417
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17418 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
17419 @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
17420
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17421 @findex triangle-bugged
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17422 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17423 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17424 (defun triangle-bugged (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17425 "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
17426 (let ((total 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17427 (while (> number 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17428 (setq total (+ total number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17429 (setq number (1= number))) ; @r{Error here.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17430 total))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17431 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17432 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17433
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17434 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
17435 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
17436 echo area.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17439 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
17440 argument of 4:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17441
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17442 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17443 (triangle-bugged 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17444 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17445
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17446 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17447 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
17448 @file{*Backtrace*} buffer that says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17449
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17450 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17451 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17452 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17453 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17454 Debugger entered--Lisp error: (void-function 1=)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17455 (1= number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17456 (setq number (1= number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17457 (while (> number 0) (setq total (+ total number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17458 (setq number (1= number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17459 (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
17460 (setq number ...)) total)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17461 triangle-bugged(4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17462 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17463 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17464 eval((triangle-bugged 4))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17465 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17466 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17467 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17468 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17469 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17470 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17471
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17472 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17473 (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
17474 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
17475 the @file{*Backtrace*} buffer.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17476
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17477 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
17478 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
17479 function @code{1=} is `void'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17480
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17481 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17482 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
17483
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17484 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17485 Symbol's function definition is void:@: 1=
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17486 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17487
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17488 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17489 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
17490 version 21.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17491
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17492 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
17493 You can read the complete backtrace.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17494
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17495 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
17496 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
17497 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
17498
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17499 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
17500 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
17501 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
17502 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
17503 what the Lisp interpreter evaluated next.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17504
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17505 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17506 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
17507
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17508 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17509 (setq number (1= number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17510 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17511
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17512 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17513 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
17514 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
17515 top:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17516
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17517 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17518 (1= number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17519 @end smallexample
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17522 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17523 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
17524
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17525 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17526 Debugger entered--Lisp error: (void-function 1=)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17527 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17528
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17529 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17530 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
17531 then run your test again.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17532
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17533 @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
17534 @section @code{debug-on-entry}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17535 @findex debug-on-entry
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17536
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17537 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
17538 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
17539 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
17540 manually.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17541
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17542 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
17543 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
17544 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
17545
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17546 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
17547 @code{debug-on-entry}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17548
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17549 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17550 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17551 Type:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17552
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17553 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17554 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
17555 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17556
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17557 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17558 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17559 Now, evaluate the following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17560
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17561 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17562 (triangle-bugged 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17563 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17564
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17565 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17566 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
17567 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
17568 function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17569
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17570 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17571 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17572 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17573 Debugger entered--entering a function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17574 * triangle-bugged(5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17575 eval((triangle-bugged 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17576 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17577 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17578 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17579 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17580 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17581 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17582 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17583 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17584
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17585 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
17586 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
17587 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17588
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17589 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17590 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17591 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17592 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
17593 * (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
17594 (setq number ...)) total)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17595 * triangle-bugged(5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17596 eval((triangle-bugged 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17597 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17598 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17599 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17600 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17601 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17602 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17603 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17604 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17605
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17606 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17607 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
17608 @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
17609 definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17610
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17611 @need 1750
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17612 Eventually, the buffer will look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17613
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17614 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17615 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17616 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17617 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
17618 * (setq number (1= number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17619 * (while (> number 0) (setq total (+ total number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17620 (setq number (1= number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17621 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17622 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17623 * (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
17624 (setq number ...)) total)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17625 * triangle-bugged(5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17626 eval((triangle-bugged 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17627 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17628 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17629 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17630 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17631 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17632 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17633 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17634 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17635
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17636 @need 1500
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17637 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17638 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
17639 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
17640 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17641
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17642 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17643 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17644 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17645 Debugger entered--Lisp error: (void-function 1=)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17646 * (1= number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17647 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17648 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17649 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17650 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17651
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17652 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
17653
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17654 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
17655 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
17656
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17657 @findex cancel-debug-on-entry
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17658 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
17659 @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
17660
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17661 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17662 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
17663 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17664
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17665 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17666 (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
17667
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17668 @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
17669 @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
17670
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17671 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
17672 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
17673
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17674 @findex debug-on-quit
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17675 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
17676 (@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
17677 @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
17678
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17679 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17680 @cindex @code{(debug)} in code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17681 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
17682 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
17683
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17684 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17685 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17686 (defun triangle-bugged (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17687 "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
17688 (let ((total 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17689 (while (> number 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17690 (setq total (+ total number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17691 (debug) ; @r{Start debugger.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17692 (setq number (1= number))) ; @r{Error here.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17693 total))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17694 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17695 @end smallexample
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 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
17698 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
17699
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17700 @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
17701 @section The @code{edebug} Source Level Debugger
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17702 @cindex Source level debugger
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17703 @findex edebug
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17704
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17705 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
17706 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
17707 shows which line you are currently executing.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17708
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17709 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
17710 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
17711
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17712 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
17713 Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17714
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17715 @need 1250
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17716 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
17717 @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
17718 for a review of it.
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17721 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17722 (defun triangle-recursively-bugged (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17723 "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
17724 Uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17725 (if (= number 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17726 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17727 (+ number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17728 (triangle-recursively-bugged
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17729 (1= number))))) ; @r{Error here.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17730 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17731 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17734 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
17735 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
17736 (@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
17737 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
17738 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
17739 Interactive mode.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17740
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17741 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17742 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
17743 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
17744 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
17745
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17746 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17747 M-x edebug-defun RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17748 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17749
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17750 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17751 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
17752 already loaded, and properly instrument the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17753
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17754 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
17755 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
17756
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17757 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17758 (triangle-recursively-bugged 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17759 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17760
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17761 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17762 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
17763 @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
17764 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
17765 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
17766 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
17767 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
17768 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
17769
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17770 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17771 =>@point{}(if (= number 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17772 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17773
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17774 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17775 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17776 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
17777 @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
17778 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17779 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17780 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
17781 (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
17782 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17783
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17784 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
17785 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
17786
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17787 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17788 =>(if @point{}(= number 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17789 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17790
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17791 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17792 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
17793 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
17794 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
17795 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
17796
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17797 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17798 Result: 3 = C-c
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17799 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17801 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17802 This means the value of @code{number} is 3, which is @sc{ascii}
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17803 `control-c' (the third letter of the alphabet, in case you need to
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17804 know this information).
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17805
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17806 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
17807 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
17808
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17809 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17810 => @point{}(1= number))))) ; @r{Error here.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17811 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17812
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17813 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17814 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17815 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
17816 that says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17817
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17818 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17819 Symbol's function definition is void:@: 1=
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17820 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17821
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17822 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17823 This is the bug.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17824
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17825 Press @kbd{q} to quit Edebug.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17826
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17827 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
17828 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
17829 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
17830 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
17831
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17832 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
17833 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
17834 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
17835 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
17836 times a function is called, and more.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17837
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17838 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
17839 Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17840
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17841 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17842 @node Debugging Exercises, , edebug, Debugging
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17843 @section Debugging Exercises
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17844
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17845 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17846 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17847 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
17848 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
17849 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
17850 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
17851 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
17852 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
17853 Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17854
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17855 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17856 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
17857 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
17858 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
17859 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
17860 completes without problems.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17861
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17862 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17863 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
17864 (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
17865 @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
17866 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
17867
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17868 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17869 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
17870 (@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
17871 @code{count-words-region} is working.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17872
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17873 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17874 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
17875 @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
17876
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17877 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17878 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
17879 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
17880 @code{edebug-Trace-fast-mode}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17881
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17882 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17883 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
17884 stopping point.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17885 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17886
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17887 @node Conclusion, the-the, Debugging, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17888 @chapter Conclusion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17889
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17890 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
17891 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
17892 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
17893 simple customizations and extensions to Emacs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17894
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17895 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
17896 teach yourself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17897
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17898 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
17899 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
17900 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
17901
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17902 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
17903 and in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17904 @ifnotinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17905 @cite{The GNU Emacs Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17906 @end ifnotinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17907 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17908 @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
17909 Emacs Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17910 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17911
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17912 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
17913 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
17914 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
17915
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17916 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
17917 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
17918 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
17919 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
17920 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
17921 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
17922
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17923 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
17924 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
17925 that takes you to sources.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17926
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17927 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
17928 @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
17929 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
17930 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
17931 function, for example, looks complicated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17932
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17933 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
17934 @code{forward-sentence} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17935 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17936 (@xref{forward-sentence}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17937 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17938 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17939 (@xref{forward-sentence, , @code{forward-sentence}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17940 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17941 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
17942 @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
17943 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
17944 function contains 27 words and symbols.
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 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
17947 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
17948 @code{current-column} and @samp{?\n}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17949
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17950 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
17951 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
17952 @ref{Review, , Review}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17953
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17954 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
17955 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
17956 function. This gives you the function documentation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17957
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17958 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
17959 @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
17960 @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
17961 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
17962 @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
17963
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17964 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
17965 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
17966 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
17967 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
17968 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
17969 (@code{find-tag}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17970
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17971 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
17972 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
17973 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
17974
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17975 (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
17976 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
17977 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
17978 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
17979 properly set up.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17980
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17981 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
17982 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
17983 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
17984 (@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
17985 @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
17986 manual.
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 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
17989 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
17990 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
17991 @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
17992 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
17993 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
17994 for the newline character.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17995
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17996 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
17997 @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
17998 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
17999 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
18000 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
18001 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
18002 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
18003 (@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
18004 Reference Manual}, for more about building.)
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 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
18007 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
18008 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
18009 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
18010 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
18011 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
18012 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
18013
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18014 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
18015 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
18016 beginning.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18017
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18018 @c ================ Appendix ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18019
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18020 @node the-the, Kill Ring, Conclusion, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18021 @appendix The @code{the-the} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18022 @findex the-the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18023 @cindex Duplicated words function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18024 @cindex Words, duplicated
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18025
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18026 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
18027 you'' near the beginning of this sentence. I find that most
57378
ec29b8d91b96 Fix typo: ``the' to ``the''.
Robert J. Chassell <bob@rattlesnake.com>
parents: 57364
diff changeset
18028 frequently, I duplicate ``the''; hence, I call the function for
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18029 detecting duplicated words, @code{the-the}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18030
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18031 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18032 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
18033 search for duplicates:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18034
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18035 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18036 \\(\\w+[ \t\n]+\\)\\1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18037 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18038
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18039 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18040 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
18041 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
18042 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
18043 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
18044 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
18045 @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
18046 @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
18047 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
18048 The GNU Emacs Lisp Reference Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18049
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18050 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
18051 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
18052 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
18053
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18054 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
18055 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
18056 @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
18057 @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
18058
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18059 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18060 \\(\\(\\w+\\)\\W*\\)\\1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18061 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18062
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18063 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18064 Again, not useful.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18065
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18066 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
18067 @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
18068 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
18069 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
18070
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18071 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18072 \\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18073 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18074
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18075 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
18076 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
18077
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18078 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
18079 @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
18080
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18081 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18082 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18083 (defun the-the ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18084 "Search forward for for a duplicated word."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18085 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18086 (message "Searching for for duplicated words ...")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18087 (push-mark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18088 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18089 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18090 ;; This regexp is not perfect
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18091 ;; but is fairly good over all:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18092 (if (re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18093 "\\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
18094 (message "Found duplicated word.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18095 (message "End of buffer")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18096 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18099 ;; Bind `the-the' to C-c \
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18100 (global-set-key "\C-c\\" 'the-the)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18101 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18102 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18103
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18104 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18105 Here is test text:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18106
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18107 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18108 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18109 one two two three four five
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18110 five six seven
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18111 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18112 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18113
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18114 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
18115 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
18116
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18117 @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
18118 @appendix Handling the Kill Ring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18119 @cindex Kill ring handling
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18120 @cindex Handling the kill ring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18121 @cindex Ring, making a list like a
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 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
18124 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
18125 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
18126 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
18127 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
18128 commands.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18129
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18130 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18131 * 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
18132 * 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
18133 * yank-pop:: Insert first element pointed to.
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18134 * ring file::
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18135 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18136
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18137 @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
18138 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18139 @appendixsec The @code{rotate-yank-pointer} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18140 @findex rotate-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18141
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18142 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
18143 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
18144 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
18145 element to point to the third element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18146
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18147 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18148 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
18149
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18150 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18151 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18152 (defun rotate-yank-pointer (arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18153 "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
18154 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18155 (let ((length (length kill-ring)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18156 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18157 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18158 (if (zerop length)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18159 ;; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18160 (error "Kill ring is empty")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18161 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18162 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18163 ;; @r{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18164 (setq kill-ring-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18165 (nthcdr (% (+ arg
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 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18168 kill-ring-yank-pointer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18169 length)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18170 kill-ring)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18171 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18172 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18173
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18174 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18175 * Understanding rotate-yk-ptr::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18176 * 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
18177 @end menu
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 @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
18180 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18181 @unnumberedsubsec @code{rotate-yank-pointer} in Outline
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18182 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18183
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18184 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
18185 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
18186 it in skeletal form:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18187
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18188 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18189 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18190 (defun rotate-yank-pointer (arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18191 "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
18192 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18193 (let @var{varlist}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18194 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18195 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18196 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18197
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18198 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
18199 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
18200 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
18201 function as a number.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18202
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18203 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
18204 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
18205
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18206 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
18207 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
18208 @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
18209 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
18210 @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
18211 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
18212 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
18213 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
18214 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
18215 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
18216
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18217 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
18218 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
18219 kill ring.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18220
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18221 @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
18222 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18223 @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
18224
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18225 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
18226 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
18227
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18228 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
18229 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
18230 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
18231 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
18232 work of the function is done.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18233
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18234 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
18235
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18236 @findex zerop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18237 @findex error
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18238 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18239 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18240 (if (zerop length) ; @r{if-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18241 (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
18242 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18243 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18244 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18245
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18246 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18247 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
18248 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
18249 @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
18250 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
18251 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
18252 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
18253 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
18254 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
18255 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
18256 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
18257 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
18258
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18259 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18260 * 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
18261 * 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
18262 * Remainder Function:: The remainder, @code{%}, function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18263 * 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
18264 * 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
18265 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18266
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18267 @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
18268 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18269 @unnumberedsubsubsec Digression about the word `error'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18270 @end ifnottex
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 (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
18273 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
18274 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
18275 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
18276 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
18277 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
18278 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
18279 exploration.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18280
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18281 (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
18282 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
18283 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
18284 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
18285 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
18286 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
18287 `cancel' would have a clearer connotation.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18288
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18289 @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
18290 @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
18291
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18292 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
18293 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
18294 in it. The code looks like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18297 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18298 (setq kill-ring-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18299 (nthcdr (% (+ arg
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18300 (- length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18301 (length kill-ring-yank-pointer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18302 length)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18303 kill-ring)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18304 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18305 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18306
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18307 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
18308 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
18309 @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
18310 (@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
18311
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18312 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
18313 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
18314
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18315 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
18316 @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
18317 @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
18318 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
18319 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
18320 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
18321 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
18322 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
18323 elements.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18324
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18325 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
18326 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
18327 @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
18328 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
18329 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
18330 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
18331 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
18332
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18333 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18334 That is, under these circumstances,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18335
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18336 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18337 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18338 (setq kill-ring-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18339 ("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
18340
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18341 (setq kill-ring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18342 ("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
18343 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18344 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18345
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18346 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18347 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18348 the code should do this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18351 (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
18352 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18353
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18354 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18355 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18356 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
18357
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18358 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18359 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18360 kill-ring-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18361 @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
18362 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18363 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18364
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18365 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
18366 the job.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18367
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18368 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
18369 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
18370 @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
18371
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18372 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18373 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
18374
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18375 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18376 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18377 (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
18378
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18379 (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
18380 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18381 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18382
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18383 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
18384 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
18385 lots of arithmetic inside of it:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18386
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18387 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18388 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18389 (% (+ arg
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18390 (- length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18391 (length kill-ring-yank-pointer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18392 length)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18393 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18394 @end smallexample
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 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
18397 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
18398
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18399 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
18400 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
18401 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
18402 @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
18403 list.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18404
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18405 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18406 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
18407
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18408 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18409 (- length (length kill-ring-yank-pointer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18410 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18411
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18412 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18413 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
18414 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
18415 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
18416 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
18417 @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
18418 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
18419 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
18420 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
18421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18422 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
18423 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
18424 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
18425
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18426 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
18427 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
18428 @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
18429 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
18430 @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
18431
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18432 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
18433 @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
18434 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
18435 @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
18436 Consequently, the value of
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 (- length (length kill-ring-yank-pointer))
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 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
18444 that the value of the whole expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18445
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18446 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18447 (+ arg (- length (length kill-ring-yank-pointer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18448 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18449
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18450 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18451 will be 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18452
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18453 @need 1200
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18454 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
18455 the expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18456
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18457 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18458 (% 1 length)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18459 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18460
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18461 @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
18462 @unnumberedsubsubsec The @code{%} remainder function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18463
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18464 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
18465 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
18466 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
18467 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
18468 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
18469 remainder of 1.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18470
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18471 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
18472 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
18473 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
18474 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
18475 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
18476 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
18477 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
18478 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
18479
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18480 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18481 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18482 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
18483
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18484 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18485 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
18486
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18487 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18488 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
18489
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18490 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18491 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
18492
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18493 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18494 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
18495
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18496 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18497 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
18498 @end itemize
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18501 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18502 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
18503
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18504 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18505 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18506 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
18507
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18508 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18509 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
18510
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18511 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18512 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
18513 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18514
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18515 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18516 and so on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18517
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18518 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18519 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
18520 evaluating
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18521
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18522 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18523 (% 1 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18524 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18525
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18526 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18527 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
18528 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
18529
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18530 @need 2000
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18531 @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
18532 @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
18533
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18534 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
18535 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
18536 @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
18537
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18538 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18539 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18540 (- length (length kill-ring-yank-pointer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18541 @result{} 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18542 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18543 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18544
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18545 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18546 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18547 therefore,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18548
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18549 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18550 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18551 (+ arg (- length (length kill-ring-yank-pointer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18552 @result{} 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18553 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18554 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18555
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18556 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18557 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18558 and consequently:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18559
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18560 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18561 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18562 (% (+ arg (- length (length kill-ring-yank-pointer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18563 length)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18564 @result{} 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18565 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18566 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18567
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18568 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18569 regardless of the value of @code{length}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18570
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18571 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18572 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18573 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
18574 simplifies to:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18575
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18576 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18577 (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
18578 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18579
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18580 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18581 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
18582 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
18583 @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
18584
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18585 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
18586 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
18587 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
18588
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18589 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
18590 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
18591 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
18592 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
18593 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
18594 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
18595 @code{rotate-yank-pointer} is 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18596
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18597 @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
18598 @unnumberedsubsubsec Pointing to the last element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18599
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18600 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
18601 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
18602 @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
18603 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
18604 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
18605 the kill ring instead.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18606
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18607 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
18608 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
18609 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
18610 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
18611
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18612 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18613 (% (+ 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
18614 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18615
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18616 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18617 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
18618 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18619
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18620 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18621 (% (+ 1 (- 5 1)) 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18622 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18623
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18624 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18625 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
18626 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
18627 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
18628 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
18629
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18630 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18631 (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
18632 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18633
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18634 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18635 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
18636 of the kill ring.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18637
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18638 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
18639 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
18640 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
18641 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
18642 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
18643 an entity with no end?)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18644
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18645 @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
18646 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18647 @appendixsec @code{yank}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18648 @findex yank
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18649
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18650 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
18651 @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
18652 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
18653
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18654 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18655 The code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18656
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18657 @smallexample
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 (defun yank (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18660 "Reinsert the last stretch of killed text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18661 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
18662 recently killed OR yanked.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18663 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
18664 (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
18665 most recently killed stretch of killed text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18666 See also the command \\[yank-pop]."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18667 @end group
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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18670 (interactive "*P")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18671 (rotate-yank-pointer (if (listp arg) 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18672 (if (eq arg '-) -1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18673 (1- arg))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18674 (push-mark (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18675 (insert (car kill-ring-yank-pointer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18676 (if (consp arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18677 (exchange-point-and-mark)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18678 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18679 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18680
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18681 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
18682 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
18683 (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
18684 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
18685 @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
18686 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
18687 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
18688 @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
18689 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
18690
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18691 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18692 * 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
18693 * 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
18694 @end menu
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 @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
18697 @unnumberedsubsubsec Passing the argument
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 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
18700 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
18701 @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
18702 looks at first sight.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18703
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18704 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
18705 @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
18706 argument passed to @code{rotate-yank-pointer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18707
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18708 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18709 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
18710
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18711 @smallexample
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 (if (listp arg) ; @r{if-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18714 0 ; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18715 (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
18716 -1 ; @r{inner if's then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18717 (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
18718 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18719 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18720
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18721 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18722 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
18723 the other.
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 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
18726 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
18727 @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
18728 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
18729 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
18730 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
18731 @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
18732 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
18733 @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
18734 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
18735 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
18736 @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
18737 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
18738 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
18739 @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
18740 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
18741 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
18742 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
18743
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18744 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
18745 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
18746 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
18747
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18748 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
18749 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
18750 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
18751 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
18752 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
18753 is what is desired.
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 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
18756 (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
18757 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
18758 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
18759 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
18760 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
18761 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
18762 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
18763 @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
18764 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
18765 yanked back, as you would expect.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18766
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18767 @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
18768 @unnumberedsubsubsec Passing a negative argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18769
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18770 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
18771 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
18772 argument, as they quite well may?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18773
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18774 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
18775 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
18776 called with a negative number, it returns the same value as if it were
44899
ebddb2618c17 Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 43431
diff changeset
18777 called with a first argument of zero. This can be seen by evaluating
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18778 the following code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18779
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18780 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
18781 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
18782 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
18783 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
18784
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18785 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18786 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18787 (% -1 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18788 @result{} -1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18789 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18792 (setq animals '(cats dogs elephants))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18793 @result{} (cats dogs elephants)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18794 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18795
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18796 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18797 (nthcdr 1 animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18798 @result{} (dogs elephants)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18799 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18801 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18802 (nthcdr 0 animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18803 @result{} (cats dogs elephants)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18804 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18805
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18806 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18807 (nthcdr -1 animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18808 @result{} (cats dogs elephants)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18809 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18810 @end smallexample
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 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
18813 @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
18814 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
18815 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
18816 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
18817 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
18818 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
18819 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
18820 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
18821
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18822 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
18823 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
18824 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
18825 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
18826 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
18827 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
18828
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18829 @node yank-pop, ring file, yank, Kill Ring
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18830 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18831 @appendixsec @code{yank-pop}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18832 @findex yank-pop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18833
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18834 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
18835 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
18836
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18837 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18838 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18839 (defun yank-pop (arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18840 (interactive "*p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18841 (if (not (eq last-command 'yank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18842 (error "Previous command was not a yank"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18843 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18844 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18845 (setq this-command 'yank)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18846 (let ((before (< (point) (mark))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18847 (delete-region (point) (mark))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18848 (rotate-yank-pointer arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18849 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18850 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18851 (set-mark (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18852 (insert (car kill-ring-yank-pointer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18853 (if before (exchange-point-and-mark))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18854 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18855 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18856
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18857 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
18858 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
18859 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
18860 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
18861 discussed elsewhere. (@xref{copy-region-as-kill}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18862
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18863 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
18864 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
18865 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
18866 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
18867 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
18868 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
18869 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
18870 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
18871 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
18872 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
18873 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
18874 That is all there is to it!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18875
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18876 @node ring file, , yank-pop, Kill Ring
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18877 @comment node-name, next, previous, up
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18878 @appendixsec The @file{ring.el} File
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18879 @cindex @file{ring.el} file
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18880
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18881 Interestingly, GNU Emacs posses a file called @file{ring.el} that
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18882 provides many of the features we just discussed. But functions such
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18883 as @code{kill-ring-yank-pointer} do not use this library, possibly
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18884 because they were written earlier.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18885
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18886 @node Full Graph, Free Software and Free Manuals, Kill Ring, Top
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18887 @appendix A Graph with Labelled Axes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18888
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18889 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
18890 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
18891 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
18892 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
18893 body itself.
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 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18896 * Labelled Example::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18897 * 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
18898 * 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
18899 * print-X-axis:: Print a horizontal label.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18900 * 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
18901 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18902
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18903 @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
18904 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18905 @unnumberedsec Labelled Example Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18906 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18907
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18908 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
18909 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
18910 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
18911 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
18912
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18913 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18914 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18915 Set up code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18916
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18917 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18918 Print Y axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18919
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18920 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18921 Print body of graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18922
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18923 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18924 Print X axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18925 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18926
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18927 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18928 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
18929
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18930 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18931 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18932 10 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18933 *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18934 * *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18935 * **
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18936 * ***
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18937 5 - * *******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18938 * *** *******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18939 *************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18940 ***************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18941 1 - ****************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18942 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18943 1 5 10 15
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18944 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18945 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18946
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18947 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18948 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
18949 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
18950 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
18951
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18952 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18953 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18954 5 - *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18955 * ** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18956 *******
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 1 - **************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18959 | ^ |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18960 Jan June Jan
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18961 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18962 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18963
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18964 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
18965 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
18966 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
18967 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
18968 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
18969
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18970 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18971 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
18972 @code{print-graph} function:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18975 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18976 (defun print-graph (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18977 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18978 (let ((height @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18979 @dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18980 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18981 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18982 (print-Y-axis height @dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18983 (graph-body-print numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18984 (print-X-axis @dots{} )))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18985 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18986 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18987
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18988 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
18989 in turn.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18990
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18991 @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
18992 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18993 @appendixsec The @code{print-graph} Varlist
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18994 @cindex @code{print-graph} varlist
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18995
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18996 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
18997 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
18998 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
18999 contents of its documentation string.)
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 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
19002 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
19003 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
19004 @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
19005 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
19006 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
19007 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
19008
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19009 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
19010 @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
19011 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
19012 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
19013 previous chapter.
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 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
19016 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
19017 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
19018
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19019 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
19020 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
19021
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19022 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19023 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19024 (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
19025 (symbol-width (length graph-blank)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19026 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19027 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19028
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19029 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19030 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
19031
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
19032 @need 2000
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19033 @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
19034 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19035 @appendixsec The @code{print-Y-axis} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19036 @cindex Axis, print vertical
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19037 @cindex Y axis printing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19038 @cindex Vertical axis printing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19039 @cindex Print vertical axis
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 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
19042 the vertical axis that looks like this:
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19046 10 -
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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19049
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19050
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19051 5 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19052
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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19055 1 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19056 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19057 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19058
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19059 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19060 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
19061 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
19062
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19063 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
19064 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
19065 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
19066 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
19067 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
19068 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
19069 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
19070 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
19071 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
19072 five.
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 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19075 * 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
19076 * 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
19077 * 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
19078 * 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
19079 * 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
19080 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19081
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19082 @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
19083 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19084 @unnumberedsubsec What height should the label be?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19085 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19086
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19087 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
19088 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
19089 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
19090 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
19091 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
19092 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
19093
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19094 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
19095 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
19096 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
19097 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
19098 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
19099 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
19100 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
19101 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
19102 is required.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19103
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19104 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
19105 divided into several smaller problems.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19106
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19107 First, consider the case when the highest value of the graph is an
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
19108 integral multiple of five---when it is 5, 10, 15, or some higher
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19109 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
19110
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19111 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
19112 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
19113 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
19114 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
19115 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
19116 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
19117 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
19118 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
19119
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19120 @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
19121 @appendixsubsec Side Trip: Compute a Remainder
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19122
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19123 @findex % @r{(remainder function)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19124 @cindex Remainder function, @code{%}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19125 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
19126 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
19127 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
19128 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
19129 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
19130 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
19131 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
19132 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
19133 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
19134 @code{rotate-yank-pointer}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19135
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19136 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
19137 expressions:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19140 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19141 (% 7 5)
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 (% 10 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19144 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19145 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19146
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19147 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19148 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
19149
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19150 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
19151 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
19152 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
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19156 (zerop (% 7 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19157 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19158
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19159 (zerop (% 10 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19160 @result{} t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19161 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19162 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19163
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19164 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
19165 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
19166
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19167 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19168 (zerop (% height 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19169 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19170
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19171 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19172 (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
19173 'max numbers-list)}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19174
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19175 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
19176 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
19177 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
19178 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
19179 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
19180 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
19181 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
19182 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
19183 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
19184 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
19185
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19186 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19187 (* (1+ (/ height 5)) 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19188 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19189
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19190 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19191 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
19192
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19193 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19194 (* (1+ (/ 12 5)) 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19195 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19196
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19197 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
19198 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
19199 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
19200 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
19201 variable is @code{Y-axis-label-spacing}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19202
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19203 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19204 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
19205 following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19206
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19207 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19208 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19209 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19210 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19211 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19212 (* (1+ (/ height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19213 Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19214 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19215 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19216
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19217 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19218 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
19219 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
19220 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
19221 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
19222
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19223 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
19224 @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
19225 @code{Y-axis-label-spacing}):
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19226 @vindex Y-axis-label-spacing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19227
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19228 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19229 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19230 (defvar Y-axis-label-spacing 5
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19231 "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
19232 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19233
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19234 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19235 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19236 (let* ((height (apply 'max numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19237 (height-of-top-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19238 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19239 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19240 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19241 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19242 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19243 (* (1+ (/ height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19244 Y-axis-label-spacing)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19245 (symbol-width (length graph-blank))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19246 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19247 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19248 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19249
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19250 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19251 (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
19252 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
19253 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
19254 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
19255 more about @code{let*}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19256
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19257 @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
19258 @appendixsubsec Construct a Y Axis Element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19259
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19260 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
19261 @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
19262 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
19263 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
19264 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
19265 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
19266
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19267 @findex number-to-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19268 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
19269 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
19270 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
19271 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
19272 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19273
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19274 @smallexample
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 (length (number-to-string 35))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19277 @result{} 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19278
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19279 (length (number-to-string 100))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19280 @result{} 3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19281 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19282 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19283
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19284 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19285 (@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
19286 see this alternative name in various sources.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19287
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19288 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
19289 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
19290 This variable is defined with @code{defvar}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19291
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19292 @vindex Y-axis-tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19293 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19294 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19295 (defvar Y-axis-tic " - "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19296 "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
19297 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19298 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19299
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19300 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
19301 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
19302
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19303 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19304 (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
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 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
19308 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
19309 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
19310
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19311 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
19312 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
19313 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
19314 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
19315 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
19316 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
19317 (just once) by @code{print-graph}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19318
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19319 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19320 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19321 (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
19322 "Construct a NUMBERed label element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19323 A numbered element looks like this ` 5 - ',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19324 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
19325 the element for the largest number."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19326 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19327 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19328 (let* ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19329 (- full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19330 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19331 (concat (number-to-string number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19332 Y-axis-tic)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19333 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19334 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19335 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19336 (make-string leading-spaces ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19337 (number-to-string number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19338 Y-axis-tic)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19339 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19340 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19341
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19342 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
19343 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
19344
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19345 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
19346 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
19347 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
19348
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19349 @findex make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19350 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
19351 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
19352 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
19353 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
19354 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
19355 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
19356 syntax for characters.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19357
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19358 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
19359 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
19360 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
19361
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19362 @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
19363 @appendixsubsec Create a Y Axis Column
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 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
19366 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
19367 as the label for the vertical axis:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19368
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19369 @findex Y-axis-column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19370 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19371 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19372 (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
19373 "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
19374 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
19375 (let (Y-axis)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19376 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19377 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19378 (while (> height 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19379 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19380 ;; @r{Insert label.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19381 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19382 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19383 (Y-axis-element height width-of-label)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19384 Y-axis))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19385 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19386 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19387 ;; @r{Else, insert blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19388 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19389 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19390 (make-string width-of-label ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19391 Y-axis)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19392 (setq height (1- height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19393 ;; @r{Insert base line.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19394 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19395 (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
19396 (nreverse Y-axis)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19397 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19398 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19399
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19400 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
19401 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
19402 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
19403 @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
19404 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
19405 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
19406 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
19407
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
19408 @need 2000
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19409 @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
19410 @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
19411
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19412 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
19413 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
19414
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19415 @findex print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19416 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19417 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19418 (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
19419 "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
19420 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
19421 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
19422 ;; 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
19423 ;; are passed by `print-graph'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19424 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19425 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19426 (let ((start (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19427 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19428 (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
19429 ;; @r{Place point ready for inserting graph.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19430 (goto-char start)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19431 ;; @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
19432 (forward-char full-Y-label-width)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19433 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19434 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19435
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19436 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
19437 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
19438 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
19439 the graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19440
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19441 You can test @code{print-Y-axis}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19442
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19443 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19444 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19445 Install
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 Y-axis-label-spacing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19450 Y-axis-tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19451 Y-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19452 Y-axis-column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19453 print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19454 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19455 @end smallexample
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19458 Copy the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19459
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19460 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19461 (print-Y-axis 12 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19462 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19463
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19464 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19465 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
19466 want the axis labels to start.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19467
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19468 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19469 Type @kbd{M-:} (@code{eval-expression}).
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19472 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
19473 with @kbd{C-y} (@code{yank)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19474
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19475 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19476 Press @key{RET} to evaluate the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19477 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19478
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19479 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
19480 @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
19481 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
19482 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
19483
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
19484 @need 2000
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19485 @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
19486 @appendixsec The @code{print-X-axis} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19487 @cindex Axis, print horizontal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19488 @cindex X axis printing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19489 @cindex Print horizontal axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19490 @cindex Horizontal axis printing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19491
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19492 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
19493 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
19494
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19495 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19496 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19497 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19498 1 5 10 15
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19499 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19500 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19501
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19502 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
19503 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
19504 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
19505 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
19506
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19507 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
19508 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
19509 @code{X-axis-label-spacing}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19510
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19511 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
19512 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
19513 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
19514 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
19515
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19516 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19517 * 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
19518 * 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
19519 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19520
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19521 @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
19522 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19523 @unnumberedsubsec Similarities and differences
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19524 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19525
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19526 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
19527 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
19528 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
19529 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
19530 @code{print-X-axis} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19531
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19532 This is a three step process:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19533
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19534 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19535 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19536 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
19537
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19538 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19539 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
19540
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19541 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19542 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
19543 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
19544 @code{print-X-axis-numbered-line}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19545 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19546
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19547 @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
19548 @appendixsubsec X Axis Tic Marks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19549
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19550 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
19551 the tic marks themselves and their spacing:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19554 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19555 (defvar X-axis-label-spacing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19556 (if (boundp 'graph-blank)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19557 (* 5 (length graph-blank)) 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19558 "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
19559 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19560 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19561
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19562 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19563 (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
19564 @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
19565 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
19566 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
19567 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
19568 error message saying
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19569 @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
19570
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19571 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19572 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
19573
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19574 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19575 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19576 (defvar X-axis-tic-symbol "|"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19577 "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
19578 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19579 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19580
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19581 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19582 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
19583
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19584 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19585 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19586 @end smallexample
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 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
19589 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
19590
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19591 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
19592 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
19593 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
19594
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19595 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19596 The code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19597
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19598 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19599 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19600 ;;; X-axis-tic-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19601 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19602 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19603 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19604 ;; @r{Make a string of blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19605 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19606 (length X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19607 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19608 ;; @r{Concatenate blanks with tic symbol.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19609 X-axis-tic-symbol)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19610 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19611 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19612 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19613
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19614 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
19615 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
19616 @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
19617
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19618 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19619 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
19620 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19621
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19622 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19623 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19624 ;; X-axis-leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19625 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19626 (make-string full-Y-label-width ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19627 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19628 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19629 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19630
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19631 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
19632 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
19633 axis:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19634
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19635 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19636 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19637 ;; X-length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19638 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19639 (length numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19640 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19641
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19642 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19643 ;; tic-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19644 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19645 (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19646 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19647
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19648 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19649 ;; number-of-X-tics
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19650 (if (zerop (% (X-length tic-width)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19651 (/ (X-length tic-width))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19652 (1+ (/ (X-length tic-width))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19653 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19654 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19655
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19656 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19657 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
19658
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19659 @findex print-X-axis-tic-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19660 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19661 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19662 (defun print-X-axis-tic-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19663 (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
19664 "Print tics for X axis."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19665 (insert X-axis-leading-spaces)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19666 (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
19667 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19668 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19669 ;; @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
19670 (insert (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19671 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19672 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19673 ;; @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
19674 (* 2 (length X-axis-tic-symbol)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19675 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19676 X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19677 @end group
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 ;; @r{Insert remaining tics.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19680 (while (> number-of-X-tics 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19681 (insert X-axis-tic-element)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19682 (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
19683 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19684 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19685
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19686 The line of numbers is equally straightforward:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19687
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19688 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19689 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
19690
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19691 @findex X-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19692 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19693 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19694 (defun X-axis-element (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19695 "Construct a numbered X axis element."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19696 (let ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19697 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19698 (length (number-to-string number)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19699 (concat (make-string leading-spaces ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19700 (number-to-string number))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19701 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19702 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19703
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19704 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
19705 the number ``1'' under the first column:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19706
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19707 @findex print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19708 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19709 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19710 (defun print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19711 (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
19712 "Print line of X-axis numbers"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19713 (let ((number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19714 (insert X-axis-leading-spaces)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19715 (insert "1")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19716 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19717 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19718 (insert (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19719 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19720 ;; @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
19721 (- (* symbol-width X-axis-label-spacing) 2)
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 (number-to-string number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19724 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19725 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19726 ;; @r{Insert remaining numbers.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19727 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19728 (while (> number-of-X-tics 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19729 (insert (X-axis-element number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19730 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19731 (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
19732 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19733 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19734
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19735 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
19736 @code{print-X-axis-tic-line} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19737 @code{print-X-axis-numbered-line}.
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 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
19740 @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
19741 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
19742 separates the two lines.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19743
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19744 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
19745 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
19746
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19747 @findex print-X-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19748 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19749 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19750 (defun print-X-axis (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19751 "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
19752 (let* ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19753 (make-string full-Y-label-width ? ))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19754 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19755 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19756 ;; 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
19757 (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
19758 (X-length (length numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19759 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19760 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19761 (X-tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19762 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19763 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19764 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19765 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19766 ;; @r{Make a string of blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19767 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19768 (length X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19769 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19770 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19771 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19772 ;; @r{Concatenate blanks with tic symbol.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19773 X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19774 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19775 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19776 (tic-number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19777 (if (zerop (% X-length tic-width))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19778 (/ X-length tic-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19779 (1+ (/ X-length tic-width)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19780 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19781 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19782 (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
19783 (insert "\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19784 (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
19785 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19786 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19787
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19788 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19789 You can test @code{print-X-axis}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19790
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19791 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19792 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19793 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
19794 @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
19795 @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
19796
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19797 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19798 Copy the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19799
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19800 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19801 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19802 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19803 (let ((full-Y-label-width 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19804 (symbol-width 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19805 (print-X-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19806 '(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
19807 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19808 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19809
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19810 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19811 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
19812 want the axis labels to start.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19813
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19814 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19815 Type @kbd{M-:} (@code{eval-expression}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19816
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19817 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19818 Yank the test expression into the minibuffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19819 with @kbd{C-y} (@code{yank)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19820
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19821 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19822 Press @key{RET} to evaluate the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19823 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19824
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19825 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19826 Emacs will print the horizontal axis like this:
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
19827 @sp 1
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19828
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19829 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19830 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19831 | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19832 1 5 10 15 20
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19833 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19834 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19835
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19836 @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
19837 @appendixsec Printing the Whole Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19838 @cindex Printing the whole graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19839 @cindex Whole graph printing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19840 @cindex Graph, printing all
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19841
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19842 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
19843
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19844 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
19845 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
19846 Axes}), but with additions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19847
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19848 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19849 Here is the outline:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19850
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19851 @smallexample
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 (defun print-graph (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19854 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19855 (let ((height @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19856 @dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19857 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19858 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19859 (print-Y-axis height @dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19860 (graph-body-print numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19861 (print-X-axis @dots{} )))
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 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19864
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19865 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19866 * The final version:: A few changes.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19867 * Test print-graph:: Run a short test.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19868 * 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
19869 * lambda:: How to write an anonymous function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19870 * 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
19871 * 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
19872 * Final printed graph:: The graph itself!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19873 @end menu
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 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
19876 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19877 @unnumberedsubsec Changes for the Final Version
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19878 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19879
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19880 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
19881 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
19882 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
19883 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
19884 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
19885
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19886 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19887 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
19888 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
19889 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19890
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19891 @findex Y-axis-column @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19892 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19893 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19894 ;;; @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19895 (defun Y-axis-column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19896 (height width-of-label &optional vertical-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19897 "Construct list of labels for Y axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19898 HEIGHT is maximum height of graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19899 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
19900 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
19901 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
19902 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
19903 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
19904 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19905 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19906 (let (Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19907 (number-per-line (or vertical-step 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19908 (while (> height 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19909 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19910 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19911 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19912 ;; @r{Insert label.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19913 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19914 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19915 (Y-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19916 (* height number-per-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19917 width-of-label)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19918 Y-axis))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19919 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19920 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19921 ;; @r{Else, insert blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19922 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19923 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19924 (make-string width-of-label ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19925 Y-axis)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19926 (setq height (1- height)))
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19929 ;; @r{Insert base line.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19930 (setq Y-axis (cons (Y-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19931 (or vertical-step 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19932 width-of-label)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19933 Y-axis))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19934 (nreverse Y-axis)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19935 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19936 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19937
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19938 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
19939 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
19940 @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
19941
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19942 @findex graph-body-print @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19943 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19944 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19945 ;;; @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19946 (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
19947 "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
19948 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
19949 HEIGHT is maximum height of graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19950 SYMBOL-WIDTH is number of each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19951 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19952 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19953 (let (from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19954 (while numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19955 (setq from-position (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19956 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19957 (column-of-graph height (car numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19958 (goto-char from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19959 (forward-char symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19960 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19961 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19962 ;; @r{Draw graph column by column.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19963 (sit-for 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19964 (setq numbers-list (cdr numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19965 ;; @r{Place point for X axis labels.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19966 (forward-line height)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19967 (insert "\n")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19968 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19969 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19970
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19971 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19972 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
19973
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19974 @findex print-graph @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19975 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19976 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19977 ;;; @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19978 (defun print-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19979 (numbers-list &optional vertical-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19980 "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
19981 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
19982 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19983
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19984 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19985 Optionally, VERTICAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19986 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
19987 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
19988 each row is five units."
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19991 (let* ((symbol-width (length graph-blank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19992 ;; @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
19993 ;; @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
19994 (height (apply 'max numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19995 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19996 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19997 (height-of-top-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19998 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19999 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20000 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20001 (* (1+ (/ height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20002 Y-axis-label-spacing)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20003 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20004 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20005 (vertical-step (or vertical-step 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20006 (full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20007 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20008 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20009 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20010 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20011 (number-to-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20012 (* height-of-top-line vertical-step))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20013 Y-axis-tic))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20014 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20015
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20016 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20017 (print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20018 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
20019 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20020 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20021 (graph-body-print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20022 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
20023 (print-X-axis numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20024 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20025 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20026
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20027 @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
20028 @appendixsubsec Testing @code{print-graph}
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20031 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
20032
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20033 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20034 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20035 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
20036 @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
20037 rest of the code.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20038
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20039 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20040 Copy the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20041
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20042 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20043 (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
20044 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20045
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20046 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20047 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
20048 want the axis labels to start.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20049
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20050 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20051 Type @kbd{M-:} (@code{eval-expression}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20052
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20053 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20054 Yank the test expression into the minibuffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20055 with @kbd{C-y} (@code{yank)}.
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20058 Press @key{RET} to evaluate the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20059 @end enumerate
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 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
20063
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20064 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20065 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20066 10 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20067
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 *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20070 ** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20071 5 - **** *
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 * *********
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20074 ************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20075 1 - *************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20076
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20077 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20078 1 5 10 15
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20079 @end group
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
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
20082 @need 1200
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20083 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
20084 @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
20085
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20086 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20087 (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
20088 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20089
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20090 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20091 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20092 The graph looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20093
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20094 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20095 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20096 20 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20097
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 ** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20101 10 - **** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20102 **** ***
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20103 * *********
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20104 ************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20105 2 - *************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20106
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20107 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20108 1 5 10 15
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20109 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20110 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20111
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20112 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20113 (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
20114 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
20115 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
20116
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20117 @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
20118 @appendixsubsec Graphing Numbers of Words and Symbols
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20119
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20120 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
20121 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
20122 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
20123 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
20124
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20125 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
20126 requisite code.
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 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20129 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
20130 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
20131 following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20132
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20133 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20134 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20135 (setq top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20136 '(10 20 30 40 50
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20137 60 70 80 90 100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20138 110 120 130 140 150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20139 160 170 180 190 200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20140 210 220 230 240 250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20141 260 270 280 290 300)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20142 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20143 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20144
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20145 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20146 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
20147
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20148 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20149 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20150 Evaluate the following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20151
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20152 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20153 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20154 (setq list-for-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20155 (defuns-per-range
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20156 (sort
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20157 (recursive-lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20158 (directory-files "/usr/local/emacs/lisp"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20159 t ".+el$"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20160 '<)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20161 top-of-ranges))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20162 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20163 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20164
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20165 @noindent
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
20166 On my old machine, this took about an hour. It looked though 303 Lisp
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20167 files in my copy of Emacs version 19.23. After all that computing,
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
20168 the @code{list-for-graph} had this value:
41421
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20171 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20172 (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
20173 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
20174 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20175 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20176
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20177 @noindent
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
20178 This means that my copy of Emacs had 537 function definitions with
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20179 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
20180 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
20181 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
20182
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20183 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
20184 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
20185
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20186 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
20187 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
20188 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
20189 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
20190
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20191 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
20192 one-fiftieth its present value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20193
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20194 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
20195 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
20196
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20197 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20198 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20199 (defun one-fiftieth (full-range)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20200 "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
20201 (mapcar '(lambda (arg) (/ arg 50)) full-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20202 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20203 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20204
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20205 @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
20206 @appendixsubsec A @code{lambda} Expression: Useful Anonymity
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20207 @cindex Anonymous function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20208 @findex lambda
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20209
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20210 @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
20211 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
20212 include its whole body.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20213
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20214 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20215 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20216 Thus,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20217
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20218 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20219 (lambda (arg) (/ arg 50))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20220 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20221
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20222 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20223 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
20224 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
20225
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
20226 @need 1200
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20227 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
20228 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
20229 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
20230 equivalent of @code{multiply-by-seven} is:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20233 (lambda (number) (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20234 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20237 (@xref{defun, , The @code{defun} Special Form}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20238
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20239 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20240 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20241 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
20242
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20243 @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
20244 @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
20245 @c clear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20246 @c set print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20247 @c lambda example diagram #1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20248 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20249 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20250 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20251 (multiply-by-seven 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20252 \_______________/ ^
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20253 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20254 function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20255 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20256 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20257 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20258 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20259 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20260 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20261 @image{lambda-1}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20262 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20263 % \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
20264 % \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
20265 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20266 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20267 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20268 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20269 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20270 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20271 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20272 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20273 (multiply-by-seven 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20274 \_______________/ ^
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20275 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20276 function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20277 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20278 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20279 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20280 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20281
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20282 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20283 This expression returns 21.
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20287 Similarly, we can write:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20288
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20289 @c lambda example diagram #2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20290 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20291 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20292 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20293 ((lambda (number) (* 7 number)) 3)
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 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20296 anonymous function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20297 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20298 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20299 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20300 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20301 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20302 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20303 @image{lambda-2}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20304 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20305 % \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
20306 % \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
20307 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20308 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20309 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20310 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20311 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20312 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20313 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20314 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20315 ((lambda (number) (* 7 number)) 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20316 \____________________________/ ^
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20317 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20318 anonymous function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20319 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20320 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20321 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20322 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20323
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20324 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20325 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20326 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
20327
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20328 @c lambda example diagram #3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20329 @ifnottex
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 ((lambda (arg) (/ arg 50)) 100)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20333 \______________________/ \_/
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20334 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20335 anonymous function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20336 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20337 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20338 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20339 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20340 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20341 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20342 @image{lambda-3}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20343 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20344 % \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
20345 % \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
20346 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20347 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20348 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20349 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20350 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20351 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20352 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20353 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20354 ((lambda (arg) (/ arg 50)) 100)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20355 \______________________/ \_/
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 anonymous function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20358 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20359 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20360 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20361 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20362
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20363 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20364 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
20365 divides that number by 50.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20366
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20367 @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
20368 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
20369 expressions derive from the Lambda Calculus.
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 @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
20372 @appendixsubsec The @code{mapcar} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20373 @findex mapcar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20374
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20375 @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
20376 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
20377 a sequence.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20378
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20379 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
20380 `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
20381 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
20382 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
20383 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
20384 first of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20385
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20386 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20387 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20388 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20389
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20390 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20391 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20392 (mapcar '1+ '(2 4 6))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20393 @result{} (3 5 7)
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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20397 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20398 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
20399 @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
20400
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20401 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
20402 all the remaining.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20403 (@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
20404 @code{apply}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20405
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20406 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20407 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
20408 anonymous function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20409
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20410 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20411 (lambda (arg) (/ arg 50))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20412 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20413
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20414 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20415 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
20416 @code{list-for-graph}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20417
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20418 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20419 The whole expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20420
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20421 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20422 (mapcar '(lambda (arg) (/ arg 50)) full-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20423 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20424
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20425 @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
20426 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
20427
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20428 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
20429 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
20430 element in @code{list-for-graph}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20431
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20432 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20433 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20434 (setq fiftieth-list-for-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20435 (one-fiftieth list-for-graph))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20436 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20437 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20438
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20439 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20440 The resulting list looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20441
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20442 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20443 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20444 (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
20445 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
20446 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20447 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20448
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20449 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20450 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
20451 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
20452 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
20453 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
20454
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20455 @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
20456 @appendixsubsec Another Bug @dots{} Most Insidious
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20457 @cindex Bug, most insidious type
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20458 @cindex Insidious type of bug
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20459
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20460 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
20461 @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
20462 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
20463 @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
20464 @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
20465
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20466 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
20467 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
20468 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
20469 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
20470 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
20471 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
20472 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
20473 eventually. A hard maxim to follow.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20474
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20475 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
20476 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
20477 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
20478 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
20479 a little thought.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20480
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20481 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20482 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
20483
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20484 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20485 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20486 (defun print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20487 (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
20488 &optional horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20489 "Print line of X-axis numbers"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20490 (let ((number X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20491 (horizontal-step (or horizontal-step 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20492 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20493 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20494 (insert X-axis-leading-spaces)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20495 ;; @r{Delete extra leading spaces.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20496 (delete-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20497 (- (1-
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20498 (length (number-to-string horizontal-step)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20499 (insert (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20500 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20501 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20502 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20503 ;; @r{Insert white space.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20504 (- (* symbol-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20505 X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20506 (1-
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20507 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20508 (number-to-string horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20509 2)
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 (number-to-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20512 (* number horizontal-step))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20513 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20514 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20515 ;; @r{Insert remaining numbers.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20516 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20517 (while (> number-of-X-tics 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20518 (insert (X-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20519 (* number horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20520 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20521 (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
20522 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20523 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20524
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20525 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20526 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
20527 @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
20528 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
20529 (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
20530
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20531 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20532 @smallexample
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 (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
20535 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20536 (print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20537 tic-number leading-spaces horizontal-step))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20538 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20539 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20540
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20541 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20542 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20543 (defun print-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20544 (numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20545 &optional vertical-step horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20546 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20547 (print-X-axis numbers-list horizontal-step))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20548 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20549 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20550 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20551
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20552 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20553 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20554 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20555 (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
20556 "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
20557 Optionally, HORIZONTAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20558 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
20559 each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20560 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20561 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20562 ;; 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
20563 ;; are passed by `print-graph'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20564 (let* ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20565 (make-string full-Y-label-width ? ))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20566 ;; 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
20567 (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
20568 (X-length (length numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20569 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20570 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20571 (X-tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20572 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20573 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20574 ;; @r{Make a string of blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20575 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20576 (length X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20577 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20578 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20579 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20580 ;; @r{Concatenate blanks with tic symbol.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20581 X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20582 (tic-number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20583 (if (zerop (% X-length tic-width))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20584 (/ X-length tic-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20585 (1+ (/ X-length tic-width)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20586 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20587
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20588 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20589 (print-X-axis-tic-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20590 tic-number leading-spaces X-tic)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20591 (insert "\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20592 (print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20593 tic-number leading-spaces horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20594 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20595 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20596
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20597 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20598 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20599 (defun print-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20600 (numbers-list &optional vertical-step horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20601 "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
20602 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
20603 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20604
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20605 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20606 Optionally, VERTICAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20607 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
20608 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
20609 each row is five units.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20610 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20611
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20612 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20613 Optionally, HORIZONTAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20614 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
20615 each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20616 (let* ((symbol-width (length graph-blank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20617 ;; @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
20618 ;; @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
20619 (height (apply 'max numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20620 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20621 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20622 (height-of-top-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20623 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20624 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20625 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20626 (* (1+ (/ height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20627 Y-axis-label-spacing)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20628 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20629 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20630 (vertical-step (or vertical-step 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20631 (full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20632 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20633 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20634 (number-to-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20635 (* height-of-top-line vertical-step))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20636 Y-axis-tic))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20637 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20638 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20639 (print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20640 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
20641 (graph-body-print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20642 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
20643 (print-X-axis numbers-list horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20644 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20645 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20646 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20647
57334
37199d6ac2c7 Add minor footnotes saying ' is an abbreviation for quote.
Robert J. Chassell <bob@rattlesnake.com>
parents: 56940
diff changeset
20648 @c qqq
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20649 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20650 Graphing Definitions Re-listed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20651
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20652 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20653 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
20654
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20655 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20656 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20657 (defvar top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20658 '(10 20 30 40 50
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20659 60 70 80 90 100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20660 110 120 130 140 150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20661 160 170 180 190 200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20662 210 220 230 240 250)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20663 "List specifying ranges for `defuns-per-range'.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20664 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20665
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20666 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20667 (defvar graph-symbol "*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20668 "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
20669 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20670
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20671 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20672 (defvar graph-blank " "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20673 "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
20674 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
20675 as graph-symbol.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20676 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20677
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20678 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20679 (defvar Y-axis-tic " - "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20680 "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
20681 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20682
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20683 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20684 (defvar Y-axis-label-spacing 5
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20685 "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
20686 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20687
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20688 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20689 (defvar X-axis-tic-symbol "|"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20690 "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
20691 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20692
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20693 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20694 (defvar X-axis-label-spacing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20695 (if (boundp 'graph-blank)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20696 (* 5 (length graph-blank)) 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20697 "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
20698 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20699 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20700
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20701 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20702 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20703 (defun count-words-in-defun ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20704 "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
20705 (beginning-of-defun)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20706 (let ((count 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20707 (end (save-excursion (end-of-defun) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20708 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20709
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 (while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20712 (and (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20713 (re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20714 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20715 end t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20716 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20717 count))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20718 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20719 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20720
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20721 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20722 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20723 (defun lengths-list-file (filename)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20724 "Return list of definitions' lengths within FILE.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20725 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
20726 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
20727 symbols in one function definition."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20728 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20729
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20730 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20731 (message "Working on `%s' ... " filename)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20732 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20733 (let ((buffer (find-file-noselect filename))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20734 (lengths-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20735 (set-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20736 (setq buffer-read-only t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20737 (widen)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20738 (goto-char (point-min))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20739 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20740
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20741 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20742 (while (re-search-forward "^(defun" nil t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20743 (setq lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20744 (cons (count-words-in-defun) lengths-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20745 (kill-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20746 lengths-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20747 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20748 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20749
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20750 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20751 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20752 (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
20753 "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
20754 (let (lengths-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20755 ;;; @r{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20756 (while list-of-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20757 (setq lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20758 (append
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20759 lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20760 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20761 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20762 ;;; @r{Generate a lengths' list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20763 (lengths-list-file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20764 (expand-file-name (car list-of-files)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20765 ;;; @r{Make files' list shorter.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20766 (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
20767 ;;; @r{Return final value of lengths' list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20768 lengths-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20769 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20770 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20771
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20772 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20773 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20774 (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
20775 "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
20776 (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
20777 (number-within-range 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20778 defuns-per-range-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20779 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20780
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20781 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20782 ;; @r{Outer loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20783 (while top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20784
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20785 ;; @r{Inner loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20786 (while (and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20787 ;; @r{Need number for numeric test.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20788 (car sorted-lengths)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20789 (< (car sorted-lengths) top-of-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20790
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20791 ;; @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
20792 (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
20793 (setq sorted-lengths (cdr sorted-lengths)))
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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20796 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20797 ;; @r{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
20798
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20799 (setq defuns-per-range-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20800 (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
20801 (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
20802
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20803 ;; @r{Move to next range.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20804 (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
20805 ;; @r{Specify next top of range value.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20806 (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
20807 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20808
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20809 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20810 ;; @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
20811 ;; @r{ the largest top-of-range value.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20812 (setq defuns-per-range-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20813 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20814 (length sorted-lengths)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20815 defuns-per-range-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20816
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20817 ;; @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
20818 ;; @r{ smallest to largest.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20819 (nreverse defuns-per-range-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20820 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20821 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20822
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20823 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20824 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20825 (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
20826 "Return list of MAX-GRAPH-HEIGHT strings;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20827 ACTUAL-HEIGHT are graph-symbols.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20828 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
20829 of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20830 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
20831 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
20832 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20833
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20834 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20835 (let ((insert-list nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20836 (number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20837 (- max-graph-height actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20838
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20839 ;; @r{Fill in @code{graph-symbols}.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20840 (while (> actual-height 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20841 (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
20842 (setq actual-height (1- actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20843 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20844
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20845 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20846 ;; @r{Fill in @code{graph-blanks}.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20847 (while (> number-of-top-blanks 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20848 (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
20849 (setq number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20850 (1- number-of-top-blanks)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20851
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20852 ;; @r{Return whole list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20853 insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20854 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20855 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20856
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20857 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20858 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20859 (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
20860 "Construct a NUMBERed label element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20861 A numbered element looks like this ` 5 - ',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20862 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
20863 the element for the largest number."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20864 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20865 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20866 (let* ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20867 (- full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20868 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20869 (concat (number-to-string number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20870 Y-axis-tic)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20871 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20872 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20873 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20874 (make-string leading-spaces ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20875 (number-to-string number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20876 Y-axis-tic)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20877 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20878 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20879
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20880 @smallexample
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 (defun print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20883 (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
20884 "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
20885 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
20886 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
20887 Optionally, print according to VERTICAL-STEP."
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20890 ;; 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
20891 ;; are passed by `print-graph'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20892 (let ((start (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20893 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20894 (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
20895 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20896 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20897 ;; @r{Place point ready for inserting graph.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20898 (goto-char start)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20899 ;; @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
20900 (forward-char full-Y-label-width)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20901 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20902 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20903
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20904 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20905 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20906 (defun print-X-axis-tic-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20907 (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
20908 "Print tics for X axis."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20909 (insert X-axis-leading-spaces)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20910 (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
20911 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20912 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20913 ;; @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
20914 (insert (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20915 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20916 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20917 ;; @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
20918 (* 2 (length X-axis-tic-symbol)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20919 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20920 X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20921 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20922 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20923 ;; @r{Insert remaining tics.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20924 (while (> number-of-X-tics 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20925 (insert X-axis-tic-element)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20926 (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
20927 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20928 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20929
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20930 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20931 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20932 (defun X-axis-element (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20933 "Construct a numbered X axis element."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20934 (let ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20935 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20936 (length (number-to-string number)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20937 (concat (make-string leading-spaces ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20938 (number-to-string number))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20939 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20940 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20941
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20942 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20943 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20944 (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
20945 "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
20946 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
20947 HEIGHT is maximum height of graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20948 SYMBOL-WIDTH is number of each column."
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20951 (let (from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20952 (while numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20953 (setq from-position (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20954 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20955 (column-of-graph height (car numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20956 (goto-char from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20957 (forward-char symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20958 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20959 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20960 ;; @r{Draw graph column by column.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20961 (sit-for 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20962 (setq numbers-list (cdr numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20963 ;; @r{Place point for X axis labels.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20964 (forward-line height)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20965 (insert "\n")))
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 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20968
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20969 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20970 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20971 (defun Y-axis-column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20972 (height width-of-label &optional vertical-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20973 "Construct list of labels for Y axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20974 HEIGHT is maximum height of graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20975 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
20976 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20977 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20978 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
20979 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
20980 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
20981 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
20982 (let (Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20983 (number-per-line (or vertical-step 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20984 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20985 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20986 (while (> height 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20987 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20988 ;; @r{Insert label.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20989 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20990 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20991 (Y-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20992 (* height number-per-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20993 width-of-label)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20994 Y-axis))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20995 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20996 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20997 ;; @r{Else, insert blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20998 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20999 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21000 (make-string width-of-label ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21001 Y-axis)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21002 (setq height (1- height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21003 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21004 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21005 ;; @r{Insert base line.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21006 (setq Y-axis (cons (Y-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21007 (or vertical-step 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21008 width-of-label)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21009 Y-axis))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21010 (nreverse Y-axis)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21011 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21012 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21013
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21014 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21015 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21016 (defun print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21017 (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
21018 &optional horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21019 "Print line of X-axis numbers"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21020 (let ((number X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21021 (horizontal-step (or horizontal-step 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21022 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21023 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21024 (insert X-axis-leading-spaces)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21025 ;; line up number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21026 (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
21027 (insert (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21028 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21029 ;; @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
21030 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21031 (1- (length (number-to-string horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21032 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21033 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21034 (number-to-string (* number horizontal-step))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21035 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21036 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21037 ;; @r{Insert remaining numbers.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21038 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21039 (while (> number-of-X-tics 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21040 (insert (X-axis-element (* number horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21041 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21042 (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
21043 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21044 @end smallexample
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21047 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21048 (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
21049 "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
21050 Optionally, HORIZONTAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21051 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
21052 each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21053 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21054 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21055 ;; 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
21056 ;; are passed by `print-graph'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21057 (let* ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21058 (make-string full-Y-label-width ? ))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21059 ;; 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
21060 (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
21061 (X-length (length numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21062 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21063 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21064 (X-tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21065 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21066 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21067 ;; @r{Make a string of blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21068 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21069 (length X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21070 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21071 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21072 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21073 ;; @r{Concatenate blanks with tic symbol.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21074 X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21075 (tic-number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21076 (if (zerop (% X-length tic-width))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21077 (/ X-length tic-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21078 (1+ (/ X-length tic-width)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21079 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21080
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21081 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21082 (print-X-axis-tic-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21083 tic-number leading-spaces X-tic)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21084 (insert "\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21085 (print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21086 tic-number leading-spaces horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21087 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21088 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21089
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21090 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21091 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21092 (defun one-fiftieth (full-range)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21093 "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
21094 (mapcar '(lambda (arg) (/ arg 50)) full-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21095 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21096 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21097
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21098 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21099 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21100 (defun print-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21101 (numbers-list &optional vertical-step horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21102 "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
21103 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
21104 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21107 Optionally, VERTICAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21108 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
21109 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
21110 each row is five units.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21111 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21112
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21113 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21114 Optionally, HORIZONTAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21115 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
21116 each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21117 (let* ((symbol-width (length graph-blank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21118 ;; @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
21119 ;; @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
21120 (height (apply 'max numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21121 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21122 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21123 (height-of-top-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21124 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21125 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21126 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21127 (* (1+ (/ height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21128 Y-axis-label-spacing)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21129 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21130 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21131 (vertical-step (or vertical-step 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21132 (full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21133 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21134 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21135 (number-to-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21136 (* height-of-top-line vertical-step))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21137 Y-axis-tic))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21138 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21139 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21140
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21141 (print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21142 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
21143 (graph-body-print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21144 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
21145 (print-X-axis numbers-list horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21146 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21147 @end smallexample
57334
37199d6ac2c7 Add minor footnotes saying ' is an abbreviation for quote.
Robert J. Chassell <bob@rattlesnake.com>
parents: 56940
diff changeset
21148 @c qqq
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21149 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21151 @page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21152 @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
21153 @appendixsubsec The Printed Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21154
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21155 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
21156 like this:
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21157 @sp 1
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21158
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21159 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21160 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21161 (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
21162 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21163 @end smallexample
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21164 @sp 1
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21165
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21166 @noindent
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21167 Here is the graph:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21168 @sp 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21169
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21170 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21171 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21172 1000 - *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21173 **
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 **
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21176 **
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21177 750 - ***
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21178 ***
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 ***
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21181 ****
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21182 500 - *****
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21183 ******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21184 ******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21185 ******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21186 *******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21187 250 - ********
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21188 ********* *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21189 *********** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21190 ************* *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21191 50 - ***************** * *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21192 | | | | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21193 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
21194 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21195 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21196
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21197 @sp 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21198
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21199 @noindent
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21200 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
21201
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21202 @node Free Software and Free Manuals, GNU Free Documentation License, Full Graph, Top
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21203 @appendix Free Software and Free Manuals
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21204
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21205 @strong{by Richard M. Stallman}
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21206 @sp 1
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21207
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21208 The biggest deficiency in free operating systems is not in the
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21209 software---it is the lack of good free manuals that we can include in
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21210 these systems. Many of our most important programs do not come with
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21211 full manuals. Documentation is an essential part of any software
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21212 package; when an important free software package does not come with a
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21213 free manual, that is a major gap. We have many such gaps today.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21214
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21215 Once upon a time, many years ago, I thought I would learn Perl. I got
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21216 a copy of a free manual, but I found it hard to read. When I asked
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21217 Perl users about alternatives, they told me that there were better
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21218 introductory manuals---but those were not free.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21219
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21220 Why was this? The authors of the good manuals had written them for
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21221 O'Reilly Associates, which published them with restrictive terms---no
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21222 copying, no modification, source files not available---which exclude
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21223 them from the free software community.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21224
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21225 That wasn't the first time this sort of thing has happened, and (to
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21226 our community's great loss) it was far from the last. Proprietary
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21227 manual publishers have enticed a great many authors to restrict their
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21228 manuals since then. Many times I have heard a GNU user eagerly tell me
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21229 about a manual that he is writing, with which he expects to help the
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21230 GNU project---and then had my hopes dashed, as he proceeded to explain
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21231 that he had signed a contract with a publisher that would restrict it
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21232 so that we cannot use it.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21233
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21234 Given that writing good English is a rare skill among programmers, we
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21235 can ill afford to lose manuals this way.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21236
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21237 @c (texinfo)uref
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21238 (The Free Software Foundation
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21239 @uref{http://www.gnu.org/doc/doc.html#DescriptionsOfGNUDocumentation, ,
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21240 sells printed copies} of free @uref{http://www.gnu.org/doc/doc.html,
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21241 GNU manuals}, too.)
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21242
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21243 Free documentation, like free software, is a matter of freedom, not
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21244 price. The problem with these manuals was not that O'Reilly Associates
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21245 charged a price for printed copies---that in itself is fine. (The Free
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21246 Software Foundation sells printed copies of free GNU manuals, too.)
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21247 But GNU manuals are available in source code form, while these manuals
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21248 are available only on paper. GNU manuals come with permission to copy
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21249 and modify; the Perl manuals do not. These restrictions are the
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21250 problems.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21251
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21252 The criterion for a free manual is pretty much the same as for free
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21253 software: it is a matter of giving all users certain
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21254 freedoms. Redistribution (including commercial redistribution) must be
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21255 permitted, so that the manual can accompany every copy of the program,
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21256 on-line or on paper. Permission for modification is crucial too.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21257
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21258 As a general rule, I don't believe that it is essential for people to
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21259 have permission to modify all sorts of articles and books. The issues
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21260 for writings are not necessarily the same as those for software. For
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21261 example, I don't think you or I are obliged to give permission to
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21262 modify articles like this one, which describe our actions and our
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21263 views.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21264
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21265 But there is a particular reason why the freedom to modify is crucial
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21266 for documentation for free software. When people exercise their right
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21267 to modify the software, and add or change its features, if they are
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21268 conscientious they will change the manual too---so they can provide
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21269 accurate and usable documentation with the modified program. A manual
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21270 which forbids programmers to be conscientious and finish the job, or
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21271 more precisely requires them to write a new manual from scratch if
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21272 they change the program, does not fill our community's needs.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21273
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21274 While a blanket prohibition on modification is unacceptable, some
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21275 kinds of limits on the method of modification pose no problem. For
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21276 example, requirements to preserve the original author's copyright
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21277 notice, the distribution terms, or the list of authors, are ok. It is
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21278 also no problem to require modified versions to include notice that
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21279 they were modified, even to have entire sections that may not be
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21280 deleted or changed, as long as these sections deal with nontechnical
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21281 topics. (Some GNU manuals have them.)
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21282
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21283 These kinds of restrictions are not a problem because, as a practical
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21284 matter, they don't stop the conscientious programmer from adapting the
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21285 manual to fit the modified program. In other words, they don't block
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21286 the free software community from making full use of the manual.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21287
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21288 However, it must be possible to modify all the technical content of
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21289 the manual, and then distribute the result in all the usual media,
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21290 through all the usual channels; otherwise, the restrictions do block
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21291 the community, the manual is not free, and so we need another manual.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21292
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21293 Unfortunately, it is often hard to find someone to write another
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21294 manual when a proprietary manual exists. The obstacle is that many
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21295 users think that a proprietary manual is good enough---so they don't
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21296 see the need to write a free manual. They do not see that the free
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21297 operating system has a gap that needs filling.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21298
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21299 Why do users think that proprietary manuals are good enough? Some have
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21300 not considered the issue. I hope this article will do something to
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21301 change that.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21302
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21303 Other users consider proprietary manuals acceptable for the same
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21304 reason so many people consider proprietary software acceptable: they
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21305 judge in purely practical terms, not using freedom as a
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21306 criterion. These people are entitled to their opinions, but since
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21307 those opinions spring from values which do not include freedom, they
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21308 are no guide for those of us who do value freedom.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21309
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21310 Please spread the word about this issue. We continue to lose manuals
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21311 to proprietary publishing. If we spread the word that proprietary
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21312 manuals are not sufficient, perhaps the next person who wants to help
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21313 GNU by writing documentation will realize, before it is too late, that
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21314 he must above all make it free.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21315
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21316 We can also encourage commercial publishers to sell free, copylefted
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21317 manuals instead of proprietary ones. One way you can help this is to
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21318 check the distribution terms of a manual before you buy it, and prefer
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21319 copylefted manuals to non-copylefted ones.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21320
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21321 @sp 2
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21322 @noindent
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21323 Note: The Free Software Foundation maintains a page on its Web site
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21324 that lists free books available from other publishers:@*
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21325 @uref{http://www.gnu.org/doc/other-free-books.html}
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21326
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21327
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21328 @node GNU Free Documentation License, Index, Free Software and Free Manuals, Top
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21329 @appendix GNU Free Documentation License
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21330
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21331 @cindex FDL, GNU Free Documentation License
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21332 @center Version 1.2, November 2002
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21333
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21334 @display
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21335 Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc.
64091
6fb026ad601f Update FSF's address.
Lute Kamstra <lute@gnu.org>
parents: 64083
diff changeset
21336 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
41421
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 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
21339 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
21340 @end display
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21341
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21342 @enumerate 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21343 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21344 PREAMBLE
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21345
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21346 The purpose of this License is to make a manual, textbook, or other
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21347 functional and useful document @dfn{free} in the sense of freedom: to
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21348 assure everyone the effective freedom to copy and redistribute it,
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21349 with or without modifying it, either commercially or noncommercially.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21350 Secondarily, this License preserves for the author and publisher a way
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21351 to get credit for their work, while not being considered responsible
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21352 for modifications made by others.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21353
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21354 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
21355 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
21356 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
21357 license designed for free software.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21358
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21359 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
21360 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
21361 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
21362 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
21363 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
21364 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
21365 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
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 APPLICABILITY AND DEFINITIONS
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21369
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21370 This License applies to any manual or other work, in any medium, that
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21371 contains a notice placed by the copyright holder saying it can be
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21372 distributed under the terms of this License. Such a notice grants a
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21373 world-wide, royalty-free license, unlimited in duration, to use that
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21374 work under the conditions stated herein. The ``Document'', below,
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21375 refers to any such manual or work. Any member of the public is a
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21376 licensee, and is addressed as ``you''. You accept the license if you
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21377 copy, modify or distribute the work in a way requiring permission
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21378 under copyright law.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21379
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21380 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
21381 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
21382 modifications and/or translated into another language.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21383
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21384 A ``Secondary Section'' is a named appendix or a front-matter section
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21385 of the Document that deals exclusively with the relationship of the
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21386 publishers or authors of the Document to the Document's overall
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21387 subject (or to related matters) and contains nothing that could fall
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21388 directly within that overall subject. (Thus, if the Document is in
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21389 part a textbook of mathematics, a Secondary Section may not explain
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21390 any mathematics.) The relationship could be a matter of historical
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21391 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
21392 commercial, philosophical, ethical or political position regarding
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21393 them.
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 ``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
21396 are designated, as being those of Invariant Sections, in the notice
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21397 that says that the Document is released under this License. If a
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21398 section does not fit the above definition of Secondary then it is not
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21399 allowed to be designated as Invariant. The Document may contain zero
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21400 Invariant Sections. If the Document does not identify any Invariant
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21401 Sections then there are none.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21402
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21403 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
21404 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21405 the Document is released under this License. A Front-Cover Text may
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21406 be at most 5 words, and a Back-Cover Text may be at most 25 words.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21407
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21408 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
21409 represented in a format whose specification is available to the
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21410 general public, that is suitable for revising the document
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21411 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
21412 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
21413 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
21414 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
21415 to text formatters. A copy made in an otherwise Transparent file
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21416 format whose markup, or absence of markup, has been arranged to thwart
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21417 or discourage subsequent modification by readers is not Transparent.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21418 An image format is not Transparent if used for any substantial amount
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21419 of text. A copy that is not ``Transparent'' is called ``Opaque''.
41421
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 Examples of suitable formats for Transparent copies include plain
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21422 @sc{ascii} without markup, Texinfo input format, La@TeX{} input
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21423 format, @acronym{SGML} or @acronym{XML} using a publicly available
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21424 @acronym{DTD}, and standard-conforming simple @acronym{HTML},
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21425 PostScript or @acronym{PDF} designed for human modification. Examples
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21426 of transparent image formats include @acronym{PNG}, @acronym{XCF} and
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21427 @acronym{JPG}. Opaque formats include proprietary formats that can be
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21428 read and edited only by proprietary word processors, @acronym{SGML} or
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21429 @acronym{XML} for which the @acronym{DTD} and/or processing tools are
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21430 not generally available, and the machine-generated @acronym{HTML},
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21431 PostScript or @acronym{PDF} produced by some word processors for
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21432 output purposes only.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21433
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21434 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
21435 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
21436 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
21437 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
21438 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
21439 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
21440
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21441 A section ``Entitled XYZ'' means a named subunit of the Document whose
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21442 title either is precisely XYZ or contains XYZ in parentheses following
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21443 text that translates XYZ in another language. (Here XYZ stands for a
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21444 specific section name mentioned below, such as ``Acknowledgements'',
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21445 ``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21446 of such a section when you modify the Document means that it remains a
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21447 section ``Entitled XYZ'' according to this definition.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21448
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21449 The Document may include Warranty Disclaimers next to the notice which
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21450 states that this License applies to the Document. These Warranty
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21451 Disclaimers are considered to be included by reference in this
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21452 License, but only as regards disclaiming warranties: any other
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21453 implication that these Warranty Disclaimers may have is void and has
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21454 no effect on the meaning of this License.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21455
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21456 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21457 VERBATIM COPYING
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21458
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21459 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
21460 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
21461 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
21462 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
21463 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
21464 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
21465 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
21466 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
21467 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
21468
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21469 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
21470 you may publicly display copies.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21471
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21472 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21473 COPYING IN QUANTITY
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21474
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21475 If you publish printed copies (or copies in media that commonly have
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21476 printed covers) of the Document, numbering more than 100, and the
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21477 Document's license notice requires Cover Texts, you must enclose the
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21478 copies in covers that carry, clearly and legibly, all these Cover
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21479 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
21480 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
21481 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
21482 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
21483 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
21484 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
21485 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
21486 as verbatim copying in other respects.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21487
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21488 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
21489 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
21490 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
21491 pages.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21492
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21493 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
21494 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
21495 copy along with each Opaque copy, or state in or with each Opaque copy
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21496 a computer-network location from which the general network-using
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21497 public has access to download using public-standard network protocols
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21498 a complete Transparent copy of the Document, free of added material.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21499 If you use the latter option, you must take reasonably prudent steps,
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21500 when you begin distribution of Opaque copies in quantity, to ensure
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21501 that this Transparent copy will remain thus accessible at the stated
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21502 location until at least one year after the last time you distribute an
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21503 Opaque copy (directly or through your agents or retailers) of that
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21504 edition to the public.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21505
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21506 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
21507 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
21508 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
21509
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21510 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21511 MODIFICATIONS
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21512
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21513 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
21514 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
21515 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
21516 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
21517 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
21518 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
21519
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21520 @enumerate A
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21521 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21522 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
21523 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
21524 (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
21525 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
21526 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
21527
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21528 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21529 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
21530 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
21531 Version, together with at least five of the principal authors of the
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21532 Document (all of its principal authors, if it has fewer than five),
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21533 unless they release you from this requirement.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21534
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21535 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21536 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
21537 Modified Version, as the publisher.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21538
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21539 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21540 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
21541
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21542 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21543 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
21544 adjacent to the other copyright notices.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21545
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21546 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21547 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
21548 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
21549 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
21550
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21551 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21552 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
21553 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
21554
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21555 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21556 Include an unaltered copy of this License.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21557
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21558 @item
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21559 Preserve the section Entitled ``History'', Preserve its Title, and add
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21560 to it an item stating at least the title, year, new authors, and
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21561 publisher of the Modified Version as given on the Title Page. If
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21562 there is no section Entitled ``History'' in the Document, create one
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21563 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
21564 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
21565 Version as stated in the previous sentence.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21566
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21567 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21568 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
21569 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
21570 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
21571 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
21572 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
21573 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
21574 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
21575
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21576 @item
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21577 For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21578 the Title of the section, and preserve in the section all the
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21579 substance and tone of each of the contributor acknowledgements and/or
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21580 dedications given therein.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21581
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21582 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21583 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
21584 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
21585 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
21586
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21587 @item
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21588 Delete any section Entitled ``Endorsements''. Such a section
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21589 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
21590
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21591 @item
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21592 Do not retitle any existing section to be Entitled ``Endorsements'' or
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21593 to conflict in title with any Invariant Section.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21594
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21595 @item
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21596 Preserve any Warranty Disclaimers.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21597 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21598
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21599 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
21600 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
21601 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
21602 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
21603 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
21604 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
21605
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21606 You may add a section Entitled ``Endorsements'', provided it contains
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21607 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
21608 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
21609 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
21610 standard.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21611
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21612 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
21613 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
21614 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
21615 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
21616 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
21617 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
21618 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
21619 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
21620 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
21621
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21622 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
21623 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
21624 imply endorsement of any Modified Version.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21625
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21626 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21627 COMBINING DOCUMENTS
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21628
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21629 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
21630 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
21631 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
21632 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
21633 list them all as Invariant Sections of your combined work in its
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21634 license notice, and that you preserve all their Warranty Disclaimers.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21635
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21636 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
21637 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
21638 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
21639 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
21640 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
21641 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
21642 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
21643 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
21644
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21645 In the combination, you must combine any sections Entitled ``History''
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21646 in the various original documents, forming one section Entitled
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21647 ``History''; likewise combine any sections Entitled ``Acknowledgements'',
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21648 and any sections Entitled ``Dedications''. You must delete all
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21649 sections Entitled ``Endorsements.''
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21650
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21651 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21652 COLLECTIONS OF DOCUMENTS
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21653
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21654 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
21655 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
21656 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
21657 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
21658 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
21659
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21660 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
21661 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
21662 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
21663 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
21664
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21665 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21666 AGGREGATION WITH INDEPENDENT WORKS
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21667
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21668 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
21669 and independent documents or works, in or on a volume of a storage or
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21670 distribution medium, is called an ``aggregate'' if the copyright
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21671 resulting from the compilation is not used to limit the legal rights
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21672 of the compilation's users beyond what the individual works permit.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21673 When the Document is included in an aggregate, this License does not
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21674 apply to the other works in the aggregate which are not themselves
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21675 derivative works of the Document.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21676
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21677 If the Cover Text requirement of section 3 is applicable to these
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21678 copies of the Document, then if the Document is less than one half of
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21679 the entire aggregate, the Document's Cover Texts may be placed on
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21680 covers that bracket the Document within the aggregate, or the
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21681 electronic equivalent of covers if the Document is in electronic form.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21682 Otherwise they must appear on printed covers that bracket the whole
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21683 aggregate.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21684
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21685 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21686 TRANSLATION
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21687
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21688 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
21689 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
21690 Replacing Invariant Sections with translations requires special
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21691 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
21692 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
21693 original versions of these Invariant Sections. You may include a
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21694 translation of this License, and all the license notices in the
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21695 Document, and any Warranty Disclaimers, provided that you also include
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21696 the original English version of this License and the original versions
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21697 of those notices and disclaimers. In case of a disagreement between
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21698 the translation and the original version of this License or a notice
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21699 or disclaimer, the original version will prevail.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21700
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21701 If a section in the Document is Entitled ``Acknowledgements'',
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21702 ``Dedications'', or ``History'', the requirement (section 4) to Preserve
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21703 its Title (section 1) will typically require changing the actual
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21704 title.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21705
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21706 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21707 TERMINATION
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21708
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21709 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
21710 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
21711 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
21712 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
21713 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
21714 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
21715 parties remain in full compliance.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21716
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21717 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21718 FUTURE REVISIONS OF THIS LICENSE
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21719
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21720 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
21721 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
21722 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
21723 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
21724 @uref{http://www.gnu.org/copyleft/}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21725
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21726 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
21727 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
21728 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
21729 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
21730 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
21731 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
21732 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
21733 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
21734 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21735
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21736 @page
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21737 @appendixsubsec ADDENDUM: How to use this License for your documents
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21738
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21739 To use this License in a document you have written, include a copy of
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21740 the License in the document and put the following copyright and
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21741 license notices just after the title page:
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21742
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21743 @smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21744 @group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21745 Copyright (C) @var{year} @var{your name}.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21746 Permission is granted to copy, distribute and/or modify this document
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21747 under the terms of the GNU Free Documentation License, Version 1.2
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21748 or any later version published by the Free Software Foundation;
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21749 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21750 A copy of the license is included in the section entitled ``GNU
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21751 Free Documentation License''.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21752 @end group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21753 @end smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21754
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21755 If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21756 replace the ``with...Texts.'' line with this:
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21757
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21758 @smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21759 @group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21760 with the Invariant Sections being @var{list their titles}, with
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21761 the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21762 being @var{list}.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21763 @end group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21764 @end smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21765
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21766 If you have Invariant Sections without Cover Texts, or some other
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21767 combination of the three, merge those two alternatives to suit the
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21768 situation.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21769
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21770 If your document contains nontrivial examples of program code, we
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21771 recommend releasing these examples in parallel under your choice of
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21772 free software license, such as the GNU General Public License,
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21773 to permit their use in free software.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21774
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21775 @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
21776 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21777 @unnumbered Index
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21778
41670
b4c633081255 (Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents: 41499
diff changeset
21779 @ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21780 MENU ENTRY: NODE NAME.
41670
b4c633081255 (Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents: 41499
diff changeset
21781 @end ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21782
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21783 @printindex cp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21784
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21785 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21786 @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
21787
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21788 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21789 \ifodd\pageno
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21790 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21791 \global\evenheadline={\hfil} \global\evenfootline={\hfil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21792 \global\oddheadline={\hfil} \global\oddfootline={\hfil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21793 \page\hbox{}\page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21794 \else
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21795 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21796 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21797 \global\evenheadline={\hfil} \global\evenfootline={\hfil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21798 \global\oddheadline={\hfil} \global\oddfootline={\hfil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21799 \page\hbox{}\page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21800 \page\hbox{}\page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21801 \fi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21802 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21803
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21804 @page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21805 @w{ }
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21806
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21807 @c ================ Biographical information ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21808
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21809 @w{ }
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21810 @sp 8
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21811 @center About the Author
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21812 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21813 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21814
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21815 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21816 @node About the Author, , Index, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21817 @unnumbered About the Author
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21818 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21819
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21820 @quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21821 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
21822 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
21823 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
21824 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
21825 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
21826 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
21827 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
21828 airplane.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21829 @end quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21830
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21831 @page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21832 @w{ }
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21833
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21834 @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
21835 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21836 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21837 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21838
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21839 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21840 @headings off
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21841 @evenheading @thispage @| @| @thistitle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21842 @oddheading @| @| @thispage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21843 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21844
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21845 @bye
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 51945
diff changeset
21846
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 51945
diff changeset
21847 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 51945
diff changeset
21848 arch-tag: da1a2154-531f-43a8-8e33-fc7faad10acf
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 51945
diff changeset
21849 @end ignore