annotate lispintro/emacs-lisp-intro.texi @ 77867:f565d6a9aaaa

Include site-lisp directory in bin-i386 distribution.
author Jason Rumney <jasonr@gnu.org>
date Sun, 03 Jun 2007 20:20:15 +0000
parents 5325e1fc379d
children a8fd89a466fd 12580d7bad1e f83d17e1ace6
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
74223
e658f2abf575 Input texinfo instead of ../man/texinfo
Andreas Schwab <schwab@suse.de>
parents: 73854
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
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
25 @set edition-number 3.07
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
26 @set update-date 9 November 2006
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/
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
32 ## pushd /u/intro/
56940
ea9bb593b003 Thanks to Christopher Allan Webber, fix typo.
Robert J. Chassell <bob@rattlesnake.com>
parents: 53099
diff changeset
33
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
34 ## Info output
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
35 makeinfo --paragraph-indent=0 --verbose emacs-lisp-intro.texi
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
36
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
37 ## ;; (progn (when (bufferp (get-buffer "*info*")) (kill-buffer "*info*")) (info "/usr/local/src/emacs/info/eintr"))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
38
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
39 ## DVI output
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
40 texi2dvi emacs-lisp-intro.texi
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
41
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
42 ## xdvi -margins 24pt -topmargin 4pt -offsets 24pt -geometry 760x1140 -s 5 -useTeXpages -mousemode 1 emacs-lisp-intro.dvi &
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
43
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
44 ## HTML output
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
45 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
46
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
47 ## galeon emacs-lisp-intro.html
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
48
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
49 ## Plain text output
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
50 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
51 --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
52
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
53 popd
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
54
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
55 # as user `root'
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
56 # insert thumbdrive
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
57 mtusb # mount -v -t ext3 /dev/sda /mnt
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
58 cp -v /u/intro/emacs-lisp-intro.texi /mnt/backup/intro/emacs-lisp-intro.texi
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
59 umtusb # umount -v /mnt
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
60 # remove thumbdrive
57334
37199d6ac2c7 Add minor footnotes saying ' is an abbreviation for quote.
Robert J. Chassell <bob@rattlesnake.com>
parents: 56940
diff changeset
61
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
62 ## Other shell commands
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
63
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
64 pushd /usr/local/src/emacs/lispintro/
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
65 ## pushd /u/intro/
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
66
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
67 ## PDF
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
68 texi2dvi --pdf emacs-lisp-intro.texi
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
69 # xpdf emacs-lisp-intro.pdf &
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
70
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
71 ## DocBook -- note file extension
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
72 makeinfo --docbook --no-split --paragraph-indent=0 \
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
73 --verbose --output=emacs-lisp-intro.docbook emacs-lisp-intro.texi
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
74
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
75 ## XML with a Texinfo DTD -- note file extension
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
76 makeinfo --xml --no-split --paragraph-indent=0 \
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
77 --verbose --output=emacs-lisp-intro.texinfoxml emacs-lisp-intro.texi
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
78
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
79 ## PostScript (needs DVI)
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
80 # gv emacs-lisp-intro.ps &
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
81 # Create DVI if we lack it
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
82 # texi2dvi emacs-lisp-intro.texi
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
83 dvips emacs-lisp-intro.dvi -o emacs-lisp-intro.ps
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
84
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
85 ## RTF (needs HTML)
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
86 # Use OpenOffice to view RTF
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
87 # Create HTML if we lack it
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
88 # makeinfo --no-split --html emacs-lisp-intro.texi
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
89 /usr/local/src/html2rtf.pl emacs-lisp-intro.html
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
90
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
91 ## LaTeX (needs RTF)
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
92 /usr/bin/rtf2latex emacs-lisp-intro.rtf
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
93
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
94 popd
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
95
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
96 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
97
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
98 @c ================ Included Figures ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
99
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
100 @c 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
101 @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
102 @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
103 @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
104 @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
105
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
106 @c ================ How to Create an Info file ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
107
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
108 @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
109
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
110 @c makeinfo emacs-lisp-intro.texi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
111
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
112 @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
113 @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
114
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
115 @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
116 @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
117 @c install the manual automatically.
75267
164280499c23 Minor comment fix.
Chong Yidong <cyd@stupidchicken.com>
parents: 74223
diff changeset
118 @c (The `dir' file is often in the `/usr/local/share/info/' directory.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
119
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
120 @c ================ How to Create an HTML file ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
121
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
122 @c To convert to HTML format
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
123 @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
124
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
125 @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
126
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
127 @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
128 @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
129
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
130 @c 7 by 9.25 inches:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
131 @c @smallbook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
132 @c @clear largebook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
133
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
134 @c 8.5 by 11 inches:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
135 @c @c smallbook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
136 @c @set largebook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
137
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
138 @c European A4 size paper:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
139 @c @c smallbook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
140 @c @afourpaper
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
141 @c @set largebook
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 ================ How to Typeset and Print ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
144
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
145 @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
146 @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
147 @c system:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
148
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
149 @c texi2dvi emacs-lisp-intro.texi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
150 @c lpr -d emacs-lisp-intro.dvi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
151
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
152 @c or else:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
153
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
154 @c tex emacs-lisp-intro.texi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
155 @c texindex emacs-lisp-intro.??
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
156 @c tex emacs-lisp-intro.texi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
157 @c lpr -d emacs-lisp-intro.dvi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
158
41499
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
159 @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
160 @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
161 @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
162 @c similar:
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
163 @c
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
164 @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
165 @c
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
166 @c or else:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
167 @c
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
168 @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
169 @c
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 (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
172 @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
173
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
174 @c ================ End of Formatting Sections ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
175
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
176 @c For next or subsequent edition:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
177 @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
178 @c create a major mode, with keymaps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
179 @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
180
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
181 @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
182 @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
183 @ifset largebook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
184 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
185 \global\parskip 6pt plus 1pt
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
186 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
187 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
188
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
189 @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
190 @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
191
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
192 @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
193 @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
194
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
195 @tex
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
196 \if \xrefprintnodename
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
197 \global\def\xrefprintnodename#1{\unskip, ``#1''}
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
198 \else
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
199 \global\def\xrefprintnodename#1{ ``#1''}
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
200 \fi
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
201 % \global\def\xrefprintnodename#1{, ``#1''}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
202 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
203
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
204 @c ----------------------------------------------------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
205
41670
b4c633081255 (Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents: 41499
diff changeset
206 @dircategory Emacs
b4c633081255 (Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents: 41499
diff changeset
207 @direntry
b4c633081255 (Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents: 41499
diff changeset
208 * Emacs Lisp Intro: (eintr).
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
209 A simple introduction to Emacs Lisp programming.
41670
b4c633081255 (Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents: 41499
diff changeset
210 @end direntry
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
211
47005
186a9c64b0fd Add version 4.2 texinfo.tex and use @copying command;
Robert J. Chassell <bob@rattlesnake.com>
parents: 46593
diff changeset
212 @copying
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
213 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
214 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
215 @sp 1
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
216 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
217 @sp 1
50622
aef53887e0ed Update copyright date and update-date.
Robert J. Chassell <bob@rattlesnake.com>
parents: 50621
diff changeset
218 Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001,
75348
3d45362f1d38 Add 2007 to copyright years.
Glenn Morris <rgm@gnu.org>
parents: 75267
diff changeset
219 2002, 2003, 2004, 2005, 2006, 2007 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
220 @sp 1
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
221
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
222 @iftex
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
223 Published by the:@*
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
224
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
225 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
226 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
227 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
228 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
229 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
230 @end iftex
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
231
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
232 @ifnottex
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
233 Published by the:
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
234
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
235 @example
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
236 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
237 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
238 Free Software Foundation, Inc. Orders: sales@@gnu.org
64083
23a17af379b1 Update FSF's address.
Lute Kamstra <lute@gnu.org>
parents: 63636
diff changeset
239 51 Franklin Street, Fifth Floor Tel: +1 (617) 542-5942
23a17af379b1 Update FSF's address.
Lute Kamstra <lute@gnu.org>
parents: 63636
diff changeset
240 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
241 @end example
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
242 @end ifnottex
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
243
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
244 @sp 1
47005
186a9c64b0fd Add version 4.2 texinfo.tex and use @copying command;
Robert J. Chassell <bob@rattlesnake.com>
parents: 46593
diff changeset
245 @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
246 ISBN 1-882114-43-4
41421
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 Permission is granted to copy, distribute and/or modify this document
65553
2c8495a2cf88 Specify GFDL version 1.2.
Romain Francoise <romain@orebokech.com>
parents: 65000
diff changeset
249 under the terms of the GNU Free Documentation License, Version 1.2 or
42621
33aa22b1c9c0 Remove Preface from the `Invariant Section' listing of the License,
Robert J. Chassell <bob@rattlesnake.com>
parents: 42562
diff changeset
250 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
251 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
252 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
253 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
254 Documentation License''.
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
255
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
256 (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
257 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
258 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
259 @end copying
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
260
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
261 @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
262 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
263 {\begingroup%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
264 \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
265 \endgroup}%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
266 {\begingroup\hbox{}\vskip 0.25in \chaprm%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
267 \centerline{Programming in Emacs Lisp}%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
268 \endgroup\page\hbox{}\page}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
269 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
270
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
271 @titlepage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
272 @sp 6
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
273 @center @titlefont{An Introduction to}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
274 @sp 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
275 @center @titlefont{Programming in Emacs Lisp}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
276 @sp 2
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
277 @center Revised Third Edition
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
278 @sp 4
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
279 @center by Robert J. Chassell
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
280
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
281 @page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
282 @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
283 @insertcopying
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
284 @end titlepage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
285
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
286 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
287 @headings off
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
288 @evenheading @thispage @| @| @thischapter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
289 @oddheading @thissection @| @| @thispage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
290 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
291
41499
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
292 @ifnothtml
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
293 @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
294 @ifset largebook
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
295 @tex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
296 \global\parskip 2pt plus 1pt
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
297 \global\advance\baselineskip by -1pt
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
298 @end tex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
299 @end ifset
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
300 @end ifnothtml
41499
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
301
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
302 @shortcontents
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
303 @contents
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
304
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
305 @ifnottex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
306 @node Top, Preface, (dir), (dir)
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
307 @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
308
47005
186a9c64b0fd Add version 4.2 texinfo.tex and use @copying command;
Robert J. Chassell <bob@rattlesnake.com>
parents: 46593
diff changeset
309 @insertcopying
41499
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
310
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
311 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
312 every node in every chapter.
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
313 @end ifnottex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
314
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
315 @c >>>> Set pageno appropriately <<<<
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
316
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
317 @c The first page of the Preface is a roman numeral; it is the first
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
318 @c right handed page after the Table of Contents; hence the following
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
319 @c setting must be for an odd negative number.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
320
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
321 @iftex
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
322 @global@pageno = -11
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
323 @end iftex
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
324
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
325 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
326 * Preface:: What to look for.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
327 * List Processing:: What is Lisp?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
328 * Practicing Evaluation:: Running several programs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
329 * Writing Defuns:: How to write function definitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
330 * 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
331 * 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
332 * 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
333 a region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
334 * car cdr & cons:: Fundamental functions in Lisp.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
335 * 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
336 * 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
337 * Yanking:: Pasting stored text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
338 * Loops & Recursion:: How to repeat a process.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
339 * Regexp Search:: Regular expression searches.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
340 * 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
341 * 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
342 * 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
343 * 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
344 * 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
345 * Conclusion:: Now you have the basics.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
346 * 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
347 * 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
348 * 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
349 * Free Software and Free Manuals::
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
350 * GNU Free Documentation License::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
351 * Index::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
352 * About the Author::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
353
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
354 @detailmenu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
355 --- The Detailed Node Listing ---
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
356
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
357 Preface
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
358
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
359 * Why:: Why learn Emacs Lisp?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
360 * 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
361 * 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
362 * Lisp History::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
363 * 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
364 * Thank You::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
365
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
366 List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
367
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
368 * Lisp Lists:: What are lists?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
369 * 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
370 * Making Errors:: Generating an error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
371 * 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
372 * Lisp Interpreter:: What the Lisp interpreter does.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
373 * Evaluation:: Running a program.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
374 * Variables:: Returning a value from a variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
375 * Arguments:: Passing information to a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
376 * 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
377 * Summary:: The major points.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
378 * Error Message Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
379
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
380 Lisp Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
381
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
382 * 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
383 * Lisp Atoms:: Elemental entities.
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
384 * Whitespace in Lists:: Formatting lists to be readable.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
385 * 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
386
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
387 The Lisp Interpreter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
388
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
389 * Complications:: Variables, Special forms, Lists within.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
390 * Byte Compiling:: Specially processing code for speed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
391
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
392 Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
393
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
394 * How the Interpreter Acts:: Returns and Side Effects...
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
395 * Evaluating Inner Lists:: Lists within lists...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
396
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
397 Variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
398
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
399 * fill-column Example::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
400 * 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
401 without a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
402 * 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
403
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
404 Arguments
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 * 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
407 * 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
408 of a variable or list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
409 * 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
410 variable number of arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
411 * 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
412 to a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
413 * message:: A useful function for sending messages.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
414
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
415 Setting the Value of a Variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
416
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
417 * Using set:: Setting values.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
418 * Using setq:: Setting a quoted value.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
419 * Counting:: Using @code{setq} to count.
41421
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 Practicing Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
422
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
423 * How to Evaluate:: Typing editing commands or @kbd{C-x C-e}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
424 causes evaluation.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
425 * Buffer Names:: Buffers and files are different.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
426 * Getting Buffers:: Getting a buffer itself, not merely its name.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
427 * Switching Buffers:: How to change to another buffer.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
428 * Buffer Size & Locations:: Where point is located and the size of
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
429 the buffer.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
430 * Evaluation Exercise::
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 How To Write Function Definitions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
433
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
434 * Primitive Functions::
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
435 * defun:: The @code{defun} special form.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
436 * Install:: Install a function definition.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
437 * Interactive:: Making a function interactive.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
438 * Interactive Options:: Different options for @code{interactive}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
439 * Permanent Installation:: Installing code permanently.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
440 * let:: Creating and initializing local variables.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
441 * if:: What if?
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
442 * else:: If--then--else expressions.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
443 * Truth & Falsehood:: What Lisp considers false and true.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
444 * save-excursion:: Keeping track of point, mark, and buffer.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
445 * Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
446 * defun Exercises::
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 Install a Function Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
449
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
450 * Effect of installation::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
451 * 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
452
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
453 Make a Function Interactive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
454
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
455 * Interactive multiply-by-seven:: An overview.
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
456 * multiply-by-seven in detail:: The interactive version.
41421
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 @code{let}
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 * Prevent confusion::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
461 * Parts of let Expression::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
462 * Sample let Expression::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
463 * Uninitialized let Variables::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
464
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
465 The @code{if} Special Form
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 * if in more detail::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
468 * 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
469
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
470 Truth and Falsehood in Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
471
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
472 * nil explained:: @code{nil} has two meanings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
473
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
474 @code{save-excursion}
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 * 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
477 * Template for save-excursion::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
478
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
479 A Few Buffer--Related Functions
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 * Finding More:: How to find more information.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
482 * 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
483 @code{point-min}, and @code{push-mark}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
484 * 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
485 * 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
486 @code{insert-buffer-substring}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
487 * Buffer Related Review:: Review.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
488 * Buffer Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
489
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
490 The Definition of @code{mark-whole-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
491
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
492 * mark-whole-buffer overview::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
493 * 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
494
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
495 The Definition of @code{append-to-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
496
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
497 * append-to-buffer overview::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
498 * append interactive:: A two part interactive expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
499 * 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
500 * 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
501
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
502 A Few More Complex Functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
503
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
504 * 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
505 * 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
506 * beginning-of-buffer:: Shows @code{goto-char},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
507 @code{point-min}, and @code{push-mark}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
508 * Second Buffer Related Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
509 * optional 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 The Definition of @code{insert-buffer}
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 * insert-buffer code::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
514 * 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
515 * 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
516 * 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
517 * 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
518 * Insert let:: Two @code{save-excursion} expressions.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
519 * New insert-buffer::
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
520
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
521 The Interactive Expression in @code{insert-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
522
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
523 * 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
524 * 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
525
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
526 Complete Definition of @code{beginning-of-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
527
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
528 * Optional Arguments::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
529 * 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
530 * beginning-of-buffer complete::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
531
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
532 @code{beginning-of-buffer} with an Argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
533
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
534 * Disentangle beginning-of-buffer::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
535 * Large buffer case::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
536 * Small buffer case::
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 Narrowing and Widening
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
539
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
540 * Narrowing advantages:: The advantages of narrowing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
541 * 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
542 * 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
543 * narrow Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
544
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
545 @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
546
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
547 * 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
548 * 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
549 * cons:: Constructing a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
550 * nthcdr:: Calling @code{cdr} repeatedly.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
551 * nth::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
552 * 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
553 * setcdr:: Changing the rest of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
554 * cons Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
555
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
556 @code{cons}
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 * Build a list::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
559 * 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
560
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
561 Cutting and Storing Text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
562
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
563 * 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
564 * 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
565 * kill-region:: Cutting text out of a region.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
566 * copy-region-as-kill:: A definition for copying text.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
567 * 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
568 * 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
569 * cons & search-fwd Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
570 * search Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
571
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
572 @code{zap-to-char}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
573
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
574 * Complete zap-to-char:: The complete implementation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
575 * 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
576 * zap-to-char body:: A short overview.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
577 * 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
578 * progn:: The @code{progn} special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
579 * 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
580
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
581 @code{kill-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
582
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
583 * Complete kill-region:: The function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
584 * condition-case:: Dealing with a problem.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
585 * Lisp macro::
41421
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 @code{copy-region-as-kill}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
588
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
589 * Complete copy-region-as-kill:: The complete function definition.
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
590 * copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
591
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
592 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
593
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
594 * last-command & this-command::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
595 * kill-append function::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
596 * kill-new function::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
597
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
598 Initializing a Variable with @code{defvar}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
599
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
600 * See variable current value::
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
601 * defvar and asterisk::
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
602
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
603 How Lists are Implemented
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
604
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
605 * Lists diagrammed::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
606 * Symbols as Chest:: Exploring a powerful metaphor.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
607 * List Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
608
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
609 Yanking Text Back
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
610
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
611 * Kill Ring Overview::
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
612 * kill-ring-yank-pointer:: The kill ring is a list.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
613 * yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable.
41421
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 Loops and Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
616
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
617 * 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
618 * dolist dotimes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
619 * Recursion:: Causing a function to call itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
620 * Looping exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
621
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
622 @code{while}
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 * 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
625 * 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
626 * 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
627 * Incrementing Loop:: A loop with an incrementing counter.
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
628 * Incrementing Loop Details::
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
629 * 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
630
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
631 Details of an Incrementing Loop
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
632
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
633 * Incrementing Example:: Counting pebbles in a triangle.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
634 * 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
635 * 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
636
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
637 Loop with a Decrementing Counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
638
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
639 * Decrementing Example:: More pebbles on the beach.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
640 * 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
641 * 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
642
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
643 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
644
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
645 * dolist::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
646 * dotimes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
647
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
648 Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
649
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
650 * Building Robots:: Same model, different serial number ...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
651 * Recursive Definition Parts:: Walk until you stop ...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
652 * 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
653 * Recursive triangle function::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
654 * Recursion with cond::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
655 * Recursive Patterns:: Often used templates.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
656 * No Deferment:: Don't store up work ...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
657 * No deferment solution::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
658
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
659 Recursion in Place of a Counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
660
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
661 * Recursive Example arg of 1 or 2::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
662 * Recursive Example arg of 3 or 4::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
663
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
664 Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
665
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
666 * Every::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
667 * Accumulate::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
668 * Keep::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
669
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
670 Regular Expression Searches
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
671
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
672 * 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
673 * 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
674 * 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
675 * forward-paragraph:: A somewhat complex example.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
676 * 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
677 * Regexp Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
678 * re-search Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
679
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
680 @code{forward-sentence}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
681
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
682 * Complete forward-sentence::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
683 * 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
684 * 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
685
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
686 @code{forward-paragraph}: a Goldmine of Functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
687
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
688 * 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
689 * fwd-para let:: The @code{let*} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
690 * 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
691
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
692 Counting: Repetition and Regexps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
693
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
694 * Why Count Words::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
695 * 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
696 * 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
697 * Counting Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
698
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
699 The @code{count-words-region} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
700
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
701 * 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
702 * 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
703
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
704 Counting Words in a @code{defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
705
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
706 * Divide and Conquer::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
707 * Words and Symbols:: What to count?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
708 * Syntax:: What constitutes a word or symbol?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
709 * 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
710 * 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
711 * 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
712 * 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
713 * 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
714 * 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
715 * 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
716
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
717 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
718
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
719 * 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
720 * append:: Attach one list to another.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
721
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
722 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
723
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
724 * Data for Display in Detail::
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
725 * Sorting:: Sorting lists.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
726 * Files List:: Making a list of files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
727 * Counting function definitions::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
728
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
729 Readying a Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
730
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
731 * Columns of a graph::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
732 * 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
733 * recursive-graph-body-print::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
734 * Printed Axes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
735 * Line Graph Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
736
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
737 Your @file{.emacs} File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
738
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
739 * Default Configuration::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
740 * 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
741 * defcustom:: Emacs will write code for you.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
742 * 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
743 * Text and Auto-fill:: Automatically wrap lines.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
744 * Mail Aliases:: Use abbreviations for email addresses.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
745 * 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
746 * Keybindings:: Create some personal keybindings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
747 * Keymaps:: More about key binding.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
748 * 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
749 * Autoload:: Make functions available.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
750 * Simple Extension:: Define a function; bind it to a key.
73597
4d65d5858190 * emacs-lisp-intro.texi: Remove version reference for X colors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73587
diff changeset
751 * X11 Colors:: Colors in X.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
752 * Miscellaneous::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
753 * 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
754
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
755 Debugging
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
756
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
757 * 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
758 * 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
759 * 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
760 * 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
761 * Debugging Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
762
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
763 Handling the Kill Ring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
764
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
765 * What the Kill Ring Does::
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
766 * current-kill::
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
767 * yank:: Paste a copy of a clipped element.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
768 * yank-pop:: Insert element pointed to.
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
769 * ring file::
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
770
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
771 The @code{current-kill} Function
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
772
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
773 * Understanding current-kill::
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
774
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
775 @code{current-kill} in Outline
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
776
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
777 * Body of current-kill::
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
778 * Digression concerning error:: How to mislead humans, but not computers.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
779 * Determining the Element::
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
780
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
781 A Graph with Labelled Axes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
782
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
783 * Labelled Example::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
784 * 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
785 * 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
786 * print-X-axis:: Print a horizontal label.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
787 * 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
788
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
789 The @code{print-Y-axis} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
790
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
791 * print-Y-axis in Detail::
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
792 * 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
793 * 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
794 * 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
795 * 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
796 * 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
797
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
798 The @code{print-X-axis} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
799
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
800 * 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
801 * 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
802
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
803 Printing the Whole Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
804
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
805 * The final version:: A few changes.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
806 * Test print-graph:: Run a short test.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
807 * 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
808 * lambda:: How to write an anonymous function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
809 * 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
810 * 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
811 * Final printed graph:: The graph itself!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
812
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
813 @end detailmenu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
814 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
815
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
816 @node Preface, List Processing, Top, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
817 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
818 @unnumbered Preface
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
819
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
820 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
821 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
822 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
823 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
824 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
825 extension to the editor.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
826
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
827 (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
828 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
829 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
830 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
831 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
832 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
833 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
834 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
835
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
836 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
837 * Why:: Why learn Emacs Lisp?
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
838 * On Reading this Text:: Read, gain familiarity, pick up habits....
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
839 * Who You Are:: For whom this is written.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
840 * Lisp History::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
841 * Note for Novices:: You can read this as a novice.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
842 * Thank You::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
843 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
844
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
845 @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
846 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
847 @unnumberedsec Why Study Emacs Lisp?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
848 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
849
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
850 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
851 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
852 you would any other programming language.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
853
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
854 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
855 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
856 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
857 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
858 can teach yourself to go further.
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 @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
861 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
862 @unnumberedsec On Reading this Text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
863
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
864 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
865 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
866 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
867 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
868 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
869 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
870 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
871 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
872 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
873 there.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
874
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
875 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
876 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
877 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
878 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
879 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
880 implemented.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
881 Also, I
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
882 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
883 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
884 having a dragon's cave of treasures.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
885
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
886 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
887 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
888 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
889 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
890 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
891 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
892 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
893 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
894 around your home town.
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 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
897 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
898 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
899 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
900 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
901 `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
902 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
903 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
904
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
905 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
906 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
907 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
908 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
909 advantage.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
910
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
911 @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
912 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
913 @unnumberedsec For Whom This is Written
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
914
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
915 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
916 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
917 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
918 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
919
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
920 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
921
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
922 @quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
923 @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
924 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
925
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
926 @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
927 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
928 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
929 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
930 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
931 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
932 @end quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
933
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
934 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
935
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
936 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
937 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
938 different context, or to review it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
939
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
940 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
941 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
942 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
943 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
944 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
945 information is formally introduced.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
946
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
947 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
948 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
949 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
950 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
951 what is important, and concentrate on it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
952
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
953 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
954 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
955 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
956 as a daunting mountain.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
957
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
958 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
959 document,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
960 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
961 @cite{The GNU Emacs Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
962 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
963 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
964 @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
965 Emacs Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
966 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
967 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
968 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
969 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
970 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
971 @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
972 when you are writing your own programs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
973
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
974 @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
975 @unnumberedsec Lisp History
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
976 @cindex Lisp history
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
977
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
978 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
979 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
980 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
981 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
982
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
983 @cindex Maclisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
984 @cindex Common Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
985 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
986 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
987 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
988 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
989 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
990
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
991 @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
992 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
993 @unnumberedsec A Note for Novices
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
994
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
995 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
996 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
997 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
998 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
999 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
1000 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
1001
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1002 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
1003 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
1004 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
1005 (@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
1006 @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
1007 @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
1008 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
1009 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
1010 @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
1011 (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
1012 @key{ALT}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1013 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
1014 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
1015 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
1016 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
1017 @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
1018 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
1019 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
1020 press the @key{\} key.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1021
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1022 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
1023 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
1024 @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
1025 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
1026 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
1027 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
1028 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
1029 Numeric Arguments, emacs, The GNU Emacs Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1030
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1031 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
1032 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
1033 (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
1034
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1035 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
1036 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
1037 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
1038
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1039 @node Thank You, , Note for Novices, Preface
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1040 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1041 @unnumberedsec Thank You
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1042
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1043 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
1044 @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
1045 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
1046 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
1047 @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
1048 encouragement. My mistakes are my own.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1049
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1050 @flushright
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1051 Robert J. Chassell
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1052 @end flushright
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1053
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1054 @c ================ Beginning of main text ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1055
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1056 @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
1057
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1058 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1059 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1060 \headings off
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1061 \ifodd\pageno
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1062 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1063 \else
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1064 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1065 \page\hbox{}\page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1066 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1067 \fi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1068 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1069
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1070 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1071 @headings off
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1072 @evenheading @thispage @| @| @thischapter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1073 @oddheading @thissection @| @| @thispage
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
1074 @global@pageno = 1
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1075 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1076
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1077 @node List Processing, Practicing Evaluation, Preface, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1078 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1079 @chapter List Processing
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 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
1082 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
1083 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
1084 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
1085 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
1086 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
1087 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
1088 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
1089 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
1090 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
1091 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
1092
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1093 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1094 * Lisp Lists:: What are lists?
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1095 * Run a Program:: Any list in Lisp is a program ready to run.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1096 * Making Errors:: Generating an error message.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1097 * Names & Definitions:: Names of symbols and function definitions.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1098 * Lisp Interpreter:: What the Lisp interpreter does.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1099 * Evaluation:: Running a program.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1100 * Variables:: Returning a value from a variable.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1101 * Arguments:: Passing information to a function.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1102 * set & setq:: Setting the value of a variable.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1103 * Summary:: The major points.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1104 * Error Message Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1105 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1106
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1107 @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
1108 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1109 @section Lisp Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1110 @cindex Lisp Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1111
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1112 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
1113 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
1114 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
1115 to be familiar with:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1116
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1117 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1118 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1119 '(rose
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1120 violet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1121 daisy
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1122 buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1123 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1124 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1125
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1126 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1127 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
1128 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
1129 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
1130 @cindex Flowers in a field
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1131
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1132 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1133 * Numbers Lists:: List have numbers, other lists, in them.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1134 * Lisp Atoms:: Elemental entities.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1135 * Whitespace in Lists:: Formatting lists to be readable.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1136 * Typing Lists:: How GNU Emacs helps you type lists.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1137 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1138
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1139 @node 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
1140 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1141 @unnumberedsubsec Numbers, Lists inside of Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1142 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1143
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1144 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
1145 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
1146 separated by whitespace.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1147
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1148 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
1149 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
1150 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
1151 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
1152 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
1153 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
1154 @samp{.} as punctuation marks.)
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1157 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
1158
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1159 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1160 '(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
1161 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1162
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1163 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
1164 @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
1165 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
1166 @samp{of}, @samp{it}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1167
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1168 @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
1169 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1170 @subsection Lisp Atoms
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1171 @cindex Lisp Atoms
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1172
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1173 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
1174 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
1175 `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
1176 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
1177 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
1178 single character symbols like @samp{+}. On the other hand, unlike an
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
1179 ancient atom, a list can be split into parts. (@xref{car cdr & cons,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
1180 , @code{car} @code{cdr} & @code{cons} Fundamental Functions}.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1181
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1182 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
1183 right next to a parenthesis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1184
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1185 @cindex @samp{empty list} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1186 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
1187 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
1188 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
1189 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
1190 @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
1191 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
1192
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1193 @cindex Symbolic expressions, introduced
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1194 @cindex @samp{expression} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1195 @cindex @samp{form} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1196 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
1197 @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
1198 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
1199 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
1200 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
1201 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
1202 as a synonym for expression.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1203
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1204 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
1205 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
1206 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
1207 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
1208 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
1209 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
1210 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
1211 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
1212 unsplittable.
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 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
1215 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
1216 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
1217 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
1218
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1219 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
1220 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
1221 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
1222 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
1223 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
1224 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
1225 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
1226 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
1227 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
1228 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
1229 parentheses, without any non-Lisp punctuation.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1230
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1231 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1232 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
1233 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
1234 @cindex Text between double quotation marks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1235
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1236 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1237 '(this list includes "text between quotation marks.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1238 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1239
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1240 @cindex @samp{string} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1241 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1242 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
1243 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
1244 @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
1245 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
1246 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
1247 used differently.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1248
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1249 @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
1250 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1251 @subsection Whitespace in Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1252 @cindex Whitespace in lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1253
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1254 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1255 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
1256 of the Lisp language,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1257
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1258 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1259 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1260 '(this list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1261 looks like this)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1262 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1263 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1264
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1265 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1266 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1267 is exactly the same as this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1268
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1269 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1270 '(this list looks like this)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1271 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1272
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1273 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
1274 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
1275 @samp{this} in that order.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1276
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1277 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
1278 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
1279 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
1280 order to tell them apart.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1281
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1282 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
1283 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
1284 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
1285 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
1286 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
1287 (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
1288 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
1289
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1290 @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
1291 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1292 @subsection GNU Emacs Helps You Type Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1293 @cindex Help typing lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1294 @cindex Formatting help
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1295
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1296 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
1297 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
1298 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
1299 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
1300 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
1301 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
1302 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
1303 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
1304 the enclosing list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1305
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1306 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
1307 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
1308 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
1309 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
1310 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
1311 Manual}, for more information about Emacs' modes.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1312
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1313 @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
1314 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1315 @section Run a Program
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1316 @cindex Run a program
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1317 @cindex Program, running one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1318
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1319 @cindex @samp{evaluate} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1320 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
1321 (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
1322 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
1323 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
1324 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
1325 three things that you really want!)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1326
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1327 @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
1328 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
1329 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
1330 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
1331 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
1332 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
1333 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
1334 @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
1335 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
1336 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
1337
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1338 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1339 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
1340 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
1341 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
1342
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1343 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1344 (+ 2 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1345 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1346
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1347 @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
1348 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1349 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
1350 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
1351 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
1352 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
1353 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
1354
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1355 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1356 '(this is a quoted list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1357 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1358
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1359 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1360 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
1361
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1362 @cindex Lisp interpreter, explained
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1363 @cindex Interpreter, Lisp, explained
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1364 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
1365 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
1366 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
1367 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
1368 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
1369
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1370 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
1371 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
1372 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
1373 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
1374 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
1375
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1376 @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
1377 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1378 @section Generate an Error Message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1379 @cindex Generate an error message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1380 @cindex Error message generation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1381
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1382 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
1383 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
1384 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
1385 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
1386 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
1387 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
1388 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
1389 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
1390
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1391 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
1392 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
1393
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1394 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
1395 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
1396 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
1397 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
1398 C-e}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1399
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1400 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1401 (this is an unquoted list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1402 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1403
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1404 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1405 What you see depends on which version of Emacs you are running. GNU
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
1406 Emacs version 22 provides more information than version 20 and before.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1407 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
1408 earlier, version 20 result.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1409
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1410 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1411 @noindent
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
1412 In GNU Emacs version 22, a @file{*Backtrace*} window will open up and
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1413 you will see the following in it:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1414
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1415 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1416 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1417 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1418 Debugger entered--Lisp error: (void-function this)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1419 (this is an unquoted list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1420 eval((this is an unquoted list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1421 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1422 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1423 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1424 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1425 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1426 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1427
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1428 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1429 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1430 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
1431 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
1432 debugger window go away, type:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1433
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1434 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1435 q
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1436 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1437
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1438 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1439 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
1440 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
1441 it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1442
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1443 @cindex @samp{function} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1444 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
1445
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1446 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
1447 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
1448 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
1449 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
1450 `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
1451 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
1452
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1453 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
1454 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
1455 @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
1456 backwards.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1457
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1458 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1459 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
1460
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1461 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1462 Debugger entered--Lisp error: (void-function this)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1463 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1464
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1465 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1466 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
1467 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
1468 @samp{void-function this}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1469
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1470 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
1471
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1472 @cindex @samp{function} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1473 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
1474 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
1475 @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
1476 computer to do something.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1477
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1478 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
1479 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
1480 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
1481
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1482 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
1483 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
1484 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
1485 contain the instructions is `void'.
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 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
1488 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
1489 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
1490 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
1491
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1492 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1493 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
1494 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
1495 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1496
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1497 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1498 Symbol's function definition is void:@: this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1499 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1501 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1502 (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
1503 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
1504 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
1505
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1506 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
1507 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
1508 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
1509 (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
1510 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
1511 moment.)
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 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
1514 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
1515 @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
1516
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1517 @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
1518 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1519 @section Symbol Names and Function Definitions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1520 @cindex Symbol names
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1521
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1522 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
1523 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
1524 @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
1525 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
1526 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
1527 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
1528 work the same way. I can be referred to as @samp{Bob}; however, I am
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
1529 not the letters @samp{B}, @samp{o}, @samp{b} but am, or was, the
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
1530 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
1531 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
1532
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1533 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
1534 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
1535 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
1536 (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
1537 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
1538
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1539 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
1540 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
1541 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
1542 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
1543 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
1544 (@xref{Install, , Install a Function Definition}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1545
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1546 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
1547 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
1548 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
1549 @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
1550 start with @samp{rmail-}.
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 Lisp Interpreter, Evaluation, Names & Definitions, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1553 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1554 @section The Lisp Interpreter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1555 @cindex Lisp interpreter, what it does
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1556 @cindex Interpreter, what it does
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1557
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1558 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
1559 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
1560 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
1561 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
1562 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
1563 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
1564 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
1565 Otherwise, the interpreter prints an error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1566
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1567 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
1568 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
1569 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
1570 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
1571 yourself or the computer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1572
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1573 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1574 * Complications:: Variables, Special forms, Lists within.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1575 * Byte Compiling:: Specially processing code for speed.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1576 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1577
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1578 @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
1579 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1580 @unnumberedsubsec Complications
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1581 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1582
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1583 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
1584 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
1585 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
1586 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
1587 in the section on variables. (@xref{Variables}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1588
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1589 @cindex Special form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1590 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
1591 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
1592 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
1593 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
1594 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
1595
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1596 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
1597 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
1598 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
1599 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
1600 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
1601 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
1602 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
1603 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
1604 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
1605 used by the enclosing expression.
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 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
1608 the next.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1609
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1610 @node Byte Compiling, , Complications, Lisp Interpreter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1611 @subsection Byte Compiling
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1612 @cindex Byte compiling
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1613
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1614 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
1615 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
1616 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
1617 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
1618 runs faster than humanly readable code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1619
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1620 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
1621 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
1622 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
1623 @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
1624 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
1625 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
1626
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1627 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
1628 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
1629 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
1630 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
1631 compilation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1632
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1633 @node Evaluation, Variables, Lisp Interpreter, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1634 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1635 @section Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1636 @cindex Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1637
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1638 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
1639 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
1640 `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
1641 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
1642 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
1643 Collegiate Dictionary}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1644
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
1645 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1646 * How the Interpreter Acts:: Returns and Side Effects...
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1647 * Evaluating Inner Lists:: Lists within lists...
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
1648 @end menu
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
1649
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
1650 @node How the Interpreter Acts, Evaluating Inner Lists, Evaluation, Evaluation
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
1651 @ifnottex
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
1652 @unnumberedsubsec How the Lisp Interpreter Acts
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
1653 @end ifnottex
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
1654
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
1655 @cindex @samp{returned value} explained
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1656 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
1657 @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
1658 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
1659 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
1660 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
1661 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
1662 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
1663 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
1664
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1665 @cindex @samp{side effect} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1666 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
1667 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
1668 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
1669 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
1670 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
1671 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
1672
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1673 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
1674 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
1675 or else produce an error.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1676
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
1677 @node Evaluating Inner Lists, , How the Interpreter Acts, Evaluation
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1678 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1679 @subsection Evaluating Inner Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1680 @cindex Inner list evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1681 @cindex Evaluating inner lists
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 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
1684 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
1685 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
1686 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
1687 expressions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1688
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1689 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1690 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
1691 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
1692
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1693 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1694 (+ 2 (+ 3 3))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1695 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1696
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1697 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1698 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
1699
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1700 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
1701 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
1702 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
1703 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
1704 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
1705
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1706 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
1707 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
1708 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
1709 @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
1710 `evaluate last symbolic expression'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1711
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1712 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
1713 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
1714 expression, or inside the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1715
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1716 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1717 Here is another copy of the expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1718
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1719 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1720 (+ 2 (+ 3 3))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1721 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1722
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1723 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1724 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
1725 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
1726 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
1727 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
1728 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
1729 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
1730 evaluates the expression @code{(+ 3 3)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1731
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1732 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
1733 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
1734 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
1735 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
1736 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
1737 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
1738 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
1739 see in the next section.
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 @node Variables, Arguments, Evaluation, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1742 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1743 @section Variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1744 @cindex Variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1745
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1746 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
1747 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
1748 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
1749 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
1750 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
1751 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
1752 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
1753 @dfn{variable}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1754
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1755 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
1756 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
1757 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
1758 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
1759 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
1760 ``great programming center''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1761
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1762 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1763 (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
1764 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
1765 string; these are discussed later.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1766 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1767
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1768 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
1769 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
1770 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
1771 changed without affecting the contents of the drawer holding the
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
1772 function definition, and vice-verse.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1773
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1774 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1775 * fill-column Example::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1776 * Void Function:: The error message for a symbol
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1777 without a function.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1778 * Void Variable:: The error message for a symbol without a value.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1779 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1780
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1781 @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
1782 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1783 @unnumberedsubsec @code{fill-column}, an Example Variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1784 @end ifnottex
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 @findex fill-column, @r{an example variable}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1787 @cindex Example variable, @code{fill-column}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1788 @cindex Variable, example of, @code{fill-column}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1789 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
1790 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
1791 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
1792 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
1793 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
1794 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
1795
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1796 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1797 fill-column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1798 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1799
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1800 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1801 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
1802 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
1803 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
1804 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
1805 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
1806 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
1807 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
1808 the value is known.
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 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
1811 @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
1812 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
1813 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
1814
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1815 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
1816 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
1817 this.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1818
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1819 @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
1820 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1821 @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
1822 @cindex Symbol without function error
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1823 @cindex Error for symbol without function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1824
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1825 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
1826 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
1827 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
1828
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1829 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
1830 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
1831 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
1832 Try evaluating this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1835 (fill-column)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1836 @end smallexample
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1839 @noindent
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
1840 In GNU Emacs version 22, you will create a @file{*Backtrace*} buffer
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1841 that says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1842
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1843 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1844 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1845 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1846 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
1847 (fill-column)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1848 eval((fill-column))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1849 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1850 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1851 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1852 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1853 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1854 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1855
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1856 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1857 (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
1858 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
1859
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
1860 @ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1861 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1862 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
1863
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1864 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1865 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
1866 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1867
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1868 @noindent
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
1869 (The message will go away as soon as you move the cursor or type
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1870 another key.)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
1871 @end ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1872
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1873 @node Void Variable, , Void Function, Variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1874 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1875 @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
1876 @cindex Symbol without value error
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1877 @cindex Error for symbol without value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1878
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1879 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
1880 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
1881 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
1882 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
1883 type @kbd{C-x C-e}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1884
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1885 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1886 (+ 2 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1887 @end smallexample
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 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1890 @noindent
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
1891 In GNU Emacs 22, you will create a @file{*Backtrace*} buffer that
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1892 says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1893
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1894 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1895 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1896 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1897 Debugger entered--Lisp error: (void-variable +)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1898 eval(+)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1899 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1900 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1901 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1902 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1903 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1904 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1905
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1906 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1907 (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
1908 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
1909
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1910 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
1911 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
1912 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
1913 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
1914 have a definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1915
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1916 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
1917 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
1918 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
1919 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
1920 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
1921 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
1922 @code{+} by itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1923
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1924 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
1925 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
1926 variable was void.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1927
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
1928 @ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1929 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1930 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
1931
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1932 @example
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1933 Symbol's value as variable is void:@: +
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1934 @end example
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1935
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1936 @noindent
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
1937 The meaning is the same as in GNU Emacs 22.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
1938 @end ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1939
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1940 @node Arguments, set & setq, Variables, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1941 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1942 @section Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1943 @cindex Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1944 @cindex Passing information to functions
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 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
1947 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
1948 as follows:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1949
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1950 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1951 (+ 2 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1952 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1953
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1954 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
1955 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
1956 the @code{+}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1957
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1958 @cindex @samp{argument} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1959 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
1960 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
1961 or @dfn{passed} to the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1962
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1963 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
1964 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
1965 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
1966 @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
1967 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
1968 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
1969 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
1970 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
1971 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
1972 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
1973 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
1974 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
1975 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
1976 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
1977 `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
1978 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
1979 (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
1980 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
1981 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
1982
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1983 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1984 * Data types:: Types of data passed to a function.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1985 * Args as Variable or List:: An argument can be the value
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1986 of a variable or list.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1987 * Variable Number of Arguments:: Some functions may take a
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1988 variable number of arguments.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1989 * Wrong Type of Argument:: Passing an argument of the wrong type
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1990 to a function.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
1991 * message:: A useful function for sending messages.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1992 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1993
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1994 @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
1995 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1996 @subsection Arguments' Data Types
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1997 @cindex Data types
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1998 @cindex Types of data
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1999 @cindex Arguments' data types
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2001 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
2002 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
2003 @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
2004 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
2005
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
2006 @need 1250
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2007 @findex concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2008 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
2009 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
2010 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
2011 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
2012 following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2013
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2014 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2015 (concat "abc" "def")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2016 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2017
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2018 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2019 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
2020
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2021 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
2022 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
2023 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
2024 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
2025 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
2026 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
2027 punctuations) from the beginning of the string.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2028
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2029 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2030 For example, if you evaluate the following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2031
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2032 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2033 (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
2034 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2035
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2036 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2037 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
2038 string and the two numbers.
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 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
2041 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
2042 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
2043 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
2044 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
2045 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
2046 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
2047 atom such as a number or symbol.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2048
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2049 @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
2050 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2051 @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
2052
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2053 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
2054 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
2055 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
2056
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2057 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2058 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
2059 C-e}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2060
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2061 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2062 (+ 2 fill-column)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2063 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2064
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2065 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2066 The value will be a number two more than what you get by evaluating
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2067 @code{fill-column} alone. For me, this is 74, because my value of
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2068 @code{fill-column} is 72.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2069
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2070 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
2071 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
2072 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
2073 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
2074 @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
2075 @code{(number-to-string (+ 2 fill-column))}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2076
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2077 @c For GNU Emacs 22, need number-to-string
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2078 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2079 (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
2080 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2081
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2082 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2083 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
2084 @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
2085 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
2086 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
2087 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
2088 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
2089 @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
2090
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2091 @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
2092 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2093 @subsection Variable Number of Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2094 @cindex Variable number of arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2095 @cindex Arguments, variable number of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2096
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2097 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
2098 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
2099 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
2100 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
2101 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
2102
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2103 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2104 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
2105
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2106 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2107 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2108 (+) @result{} 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2109
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2110 (*) @result{} 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2111 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2112 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2113
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2114 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2115 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
2116
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2117 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2118 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2119 (+ 3) @result{} 3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2120
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2121 (* 3) @result{} 3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2122 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2123 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2124
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2125 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2126 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
2127
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 (+ 3 4 5) @result{} 12
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2131
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2132 (* 3 4 5) @result{} 60
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2133 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2134 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2135
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2136 @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
2137 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2138 @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
2139 @cindex Wrong type of argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2140 @cindex Argument, wrong type of
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 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
2143 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
2144 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
2145 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
2146 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
2147 @kbd{C-x C-e}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2148
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2149 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2150 (+ 2 'hello)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2151 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2152
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2153 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2154 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
2155 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
2156 @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
2157 @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
2158 could not carry out its addition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2159
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2160 @need 1250
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2161 In GNU Emacs version 22, you will create and enter a
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2162 @file{*Backtrace*} buffer that says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2163
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2164 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2165 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2166 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2167 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2168 Debugger entered--Lisp error:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2169 (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
2170 +(2 hello)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2171 eval((+ 2 (quote hello)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2172 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2173 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2174 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2175 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2176 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2177 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2178
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2179 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2180 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
2181 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
2182 the abbreviation @code{'hello}.}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2183
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2184 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
2185 @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
2186 @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
2187 kind of argument the @code{+} expected.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2188
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2189 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
2190 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
2191 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
2192 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
2193 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
2194 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
2195 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
2196 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
2197 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
2198 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
2199 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
2200 numeric value of marker positions as numbers.
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 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
2203 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
2204 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
2205 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
2206 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
2207 @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
2208 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
2209 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
2210 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
2211 @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
2212
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2213 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
2214 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
2215 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
2216 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
2217 @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
2218
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2219 @ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2220 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2221 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
2222 message that says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2223
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2224 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2225 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
2226 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2227
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2228 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
2229 @file{*Backtrace*} buffer.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2230 @end ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2231
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2232 @node message, , Wrong Type of Argument, Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2233 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2234 @subsection The @code{message} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2235 @findex message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2236
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2237 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
2238 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
2239 that we will describe it here.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2240
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2241 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2242 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
2243 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
2244
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2245 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2246 (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
2247 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2248
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2249 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
2250 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
2251 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
2252 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
2253 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
2254 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
2255 @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
2256 detail}, for an example of this.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2257
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2258 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
2259 @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
2260 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
2261 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
2262 @samp{%s} is.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2263
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2264 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2265 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
2266 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
2267
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2268 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2269 (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
2270 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2271
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2272 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2273 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
2274 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
2275 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
2276 of @code{%s}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2277
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2278 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
2279 @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
2280 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
2281
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2282 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2283 (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
2284 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2285
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2286 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2287 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
2288 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
2289 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
2290 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
2291 anything that is not a number.}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2292
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2293 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
2294 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
2295 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
2296 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
2297
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2298 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2299 For example, if you evaluate the following,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2300
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2301 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2302 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2303 (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
2304 (- fill-column 14) "pink elephants")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2305 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2306 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2307
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2308 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2309 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
2310 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
2311
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2312 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
2313 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
2314 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
2315 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
2316 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
2317
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2318 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
2319 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
2320 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
2321 for @samp{%s}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2322
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2323 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2324 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2325 (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
2326 (- fill-column 32)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2327 (concat "red "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2328 (substring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2329 "The quick brown foxes jumped." 16 21)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2330 " leaping."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2331 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2332 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2333
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2334 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
2335 @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
2336 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
2337 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
2338 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
2339 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
2340
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2341 When your fill column is 70 and you evaluate the expression, the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2342 message @code{"He saw 38 red foxes leaping."} appears in your echo
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2343 area.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2344
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2345 @node set & setq, Summary, Arguments, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2346 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2347 @section Setting the Value of a Variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2348 @cindex Variable, setting value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2349 @cindex Setting value of variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2350
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2351 @cindex @samp{bind} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2352 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
2353 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
2354 @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
2355 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
2356
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2357 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
2358 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
2359
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2360 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
2361 * Using set:: Setting values.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
2362 * Using setq:: Setting a quoted value.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
2363 * Counting:: Using @code{setq} to count.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2364 @end menu
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 @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
2367 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2368 @subsection Using @code{set}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2369 @findex set
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2370
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2371 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
2372 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
2373 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
2374
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2375 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2376 (set 'flowers '(rose violet daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2377 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2378
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2379 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2380 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
2381 area. This is what is @emph{returned} by the @code{set} function. As a
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2382 side effect, the symbol @code{flowers} is bound to the list; that is,
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2383 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
2384 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
2385 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
2386 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
2387 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
2388 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
2389
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2390 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
2391 @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
2392 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
2393
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2394 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2395 flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2396 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2397
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2398 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2399 When you evaluate @code{flowers}, the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2400 @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
2401
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2402 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
2403 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
2404 @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
2405
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2406 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2407 'flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2408 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2409
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2410 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
2411 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
2412 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
2413 @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
2414 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
2415 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
2416 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
2417 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
2418 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
2419 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
2420 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
2421 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
2422
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2423 @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
2424 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2425 @subsection Using @code{setq}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2426 @findex setq
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2427
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2428 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
2429 @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
2430 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
2431 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
2432 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
2433 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
2434 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
2435
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2436 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
2437 @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
2438 is used:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2439
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2440 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2441 (setq carnivores '(lion tiger leopard))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2442 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2445 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
2446 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
2447 means @code{quote}.)
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2450 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
2451
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2452 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2453 (set 'carnivores '(lion tiger leopard))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2454 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2455
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2456 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
2457 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
2458 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
2459 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
2460 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
2461 to the symbol @code{herbivores}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2462
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2463 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2464 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2465 (setq trees '(pine fir oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2466 herbivores '(gazelle antelope zebra))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2467 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2468 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2469
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2470 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2471 (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
2472 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
2473 formatted lists.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2474
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2475 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
2476 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
2477 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
2478 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
2479 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
2480 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
2481 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
2482 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
2483
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2484 @node Counting, , Using setq, set & setq
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2485 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2486 @subsection Counting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2487 @cindex Counting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2488
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2489 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
2490 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
2491 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
2492 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
2493 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
2494 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
2495 @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
2496 evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2497
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2498 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2499 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2500 (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
2501
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2502 (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
2503
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2504 counter ; @r{This is the counter.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2505 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2506 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2507
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2508 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2509 (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
2510 defun, , Change a Function Definition}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2511
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2512 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
2513 @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
2514 @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
2515 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
2516 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
2517 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
2518 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
2519 the counter will be incremented.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2520
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2521 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
2522 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
2523 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
2524 @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
2525 @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
2526 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
2527 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
2528 @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
2529 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
2530
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2531 @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
2532 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2533 @section Summary
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 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
2536 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
2537 becomes easier as you progress onwards.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2538
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
2539 @need 1000
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2540 In summary,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2541
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2542 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2543
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2544 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2545 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
2546
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2547 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2548 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
2549 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
2550
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2551 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2552 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
2553 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
2554 quotation marks, or numbers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2555
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2556 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2557 A number evaluates to itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2558
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2559 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2560 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
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 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
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 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
2567 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
2568 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
2569
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2570 @item
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2571 A single quotation mark,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2572 @ifinfo
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2573 '
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2574 @end ifinfo
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2575 @ifnotinfo
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2576 @code{'}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2577 @end ifnotinfo
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2578 , tells the Lisp interpreter that it should
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2579 return the following expression as written, and not evaluate it as it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2580 would if the quote were not there.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2581
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2582 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2583 Arguments are the information passed to a function. The arguments to a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2584 function are computed by evaluating the rest of the elements of the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2585 of which the function is the first element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2586
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2587 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2588 A function always returns a value when it is evaluated (unless it gets
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2589 an error); in addition, it may also carry out some action called a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2590 ``side effect''. In many cases, a function's primary purpose is to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2591 create a side effect.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2592 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2593
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2594 @node Error Message Exercises, , Summary, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2595 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2596 @section Exercises
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2597
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2598 A few simple exercises:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2599
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2600 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2601 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2602 Generate an error message by evaluating an appropriate symbol that is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2603 not within parentheses.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2604
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2605 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2606 Generate an error message by evaluating an appropriate symbol that is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2607 between parentheses.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2608
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2609 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2610 Create a counter that increments by two rather than one.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2611
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2612 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2613 Write an expression that prints a message in the echo area when
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2614 evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2615 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2616
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2617 @node Practicing Evaluation, Writing Defuns, List Processing, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2618 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2619 @chapter Practicing Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2620 @cindex Practicing evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2621 @cindex Evaluation practice
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2622
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2623 Before learning how to write a function definition in Emacs Lisp, it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2624 useful to spend a little time evaluating various expressions that have
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2625 already been written. These expressions will be lists with the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2626 functions as their first (and often only) element. Since some of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2627 functions associated with buffers are both simple and interesting, we
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2628 will start with those. In this section, we will evaluate a few of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2629 these. In another section, we will study the code of several other
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2630 buffer-related functions, to see how they were written.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2631
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2632 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
2633 * How to Evaluate:: Typing editing commands or @kbd{C-x C-e}
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
2634 causes evaluation.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
2635 * Buffer Names:: Buffers and files are different.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
2636 * Getting Buffers:: Getting a buffer itself, not merely its name.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
2637 * Switching Buffers:: How to change to another buffer.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
2638 * Buffer Size & Locations:: Where point is located and the size of
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
2639 the buffer.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2640 * Evaluation Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2641 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2642
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2643 @node How to Evaluate, Buffer Names, Practicing Evaluation, Practicing Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2644 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2645 @unnumberedsec How to Evaluate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2646 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2647
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2648 @i{Whenever you give an editing command} to Emacs Lisp, such as the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2649 command to move the cursor or to scroll the screen, @i{you are evaluating
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2650 an expression,} the first element of which is a function. @i{This is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2651 how Emacs works.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2652
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2653 @cindex @samp{interactive function} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2654 @cindex @samp{command} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2655 When you type keys, you cause the Lisp interpreter to evaluate an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2656 expression and that is how you get your results. Even typing plain text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2657 involves evaluating an Emacs Lisp function, in this case, one that uses
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2658 @code{self-insert-command}, which simply inserts the character you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2659 typed. The functions you evaluate by typing keystrokes are called
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2660 @dfn{interactive} functions, or @dfn{commands}; how you make a function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2661 interactive will be illustrated in the chapter on how to write function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2662 definitions. @xref{Interactive, , Making a Function Interactive}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2663
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2664 In addition to typing keyboard commands, we have seen a second way to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2665 evaluate an expression: by positioning the cursor after a list and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2666 typing @kbd{C-x C-e}. This is what we will do in the rest of this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2667 section. There are other ways to evaluate an expression as well; these
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2668 will be described as we come to them.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2669
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2670 Besides being used for practicing evaluation, the functions shown in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2671 next few sections are important in their own right. A study of these
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2672 functions makes clear the distinction between buffers and files, how to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2673 switch to a buffer, and how to determine a location within it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2674
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2675 @node Buffer Names, Getting Buffers, How to Evaluate, Practicing Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2676 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2677 @section Buffer Names
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2678 @findex buffer-name
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2679 @findex buffer-file-name
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2680
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2681 The two functions, @code{buffer-name} and @code{buffer-file-name}, show
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2682 the difference between a file and a buffer. When you evaluate the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2683 following expression, @code{(buffer-name)}, the name of the buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2684 appears in the echo area. When you evaluate @code{(buffer-file-name)},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2685 the name of the file to which the buffer refers appears in the echo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2686 area. Usually, the name returned by @code{(buffer-name)} is the same as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2687 the name of the file to which it refers, and the name returned by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2688 @code{(buffer-file-name)} is the full path-name of the file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2690 A file and a buffer are two different entities. A file is information
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2691 recorded permanently in the computer (unless you delete it). A buffer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2692 on the other hand, is information inside of Emacs that will vanish at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2693 the end of the editing session (or when you kill the buffer). Usually,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2694 a buffer contains information that you have copied from a file; we say
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2695 the buffer is @dfn{visiting} that file. This copy is what you work on
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2696 and modify. Changes to the buffer do not change the file, until you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2697 save the buffer. When you save the buffer, the buffer is copied to the file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2698 and is thus saved permanently.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2699
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2700 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2701 If you are reading this in Info inside of GNU Emacs, you can evaluate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2702 each of the following expressions by positioning the cursor after it and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2703 typing @kbd{C-x C-e}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2704
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2705 @example
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2706 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2707 (buffer-name)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2708
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2709 (buffer-file-name)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2710 @end group
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2711 @end example
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2712
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2713 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2714 When I do this in Info, the value returned by evaluating
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2715 @code{(buffer-name)} is @file{"*info*"}, and the value returned by
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2716 evaluating @code{(buffer-file-name)} is @file{nil}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2717
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2718 On the other hand, while I am writing this Introduction, the value
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2719 returned by evaluating @code{(buffer-name)} is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2720 @file{"introduction.texinfo"}, and the value returned by evaluating
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2721 @code{(buffer-file-name)} is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2722 @file{"/gnu/work/intro/introduction.texinfo"}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2723
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2724 @cindex @code{nil}, history of word
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2725 The former is the name of the buffer and the latter is the name of the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2726 file. In Info, the buffer name is @file{"*info*"}. Info does not
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2727 point to any file, so the result of evaluating
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2728 @code{(buffer-file-name)} is @file{nil}. The symbol @code{nil} is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2729 from the Latin word for `nothing'; in this case, it means that the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2730 buffer is not associated with any file. (In Lisp, @code{nil} is also
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2731 used to mean `false' and is a synonym for the empty list, @code{()}.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2732
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2733 When I am writing, the name of my buffer is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2734 @file{"introduction.texinfo"}. The name of the file to which it
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2735 points is @file{"/gnu/work/intro/introduction.texinfo"}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2736
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2737 (In the expressions, the parentheses tell the Lisp interpreter to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2738 treat @w{@code{buffer-name}} and @w{@code{buffer-file-name}} as
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2739 functions; without the parentheses, the interpreter would attempt to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2740 evaluate the symbols as variables. @xref{Variables}.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2741
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2742 In spite of the distinction between files and buffers, you will often
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
2743 find that people refer to a file when they mean a buffer and vice-verse.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2744 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
2745 ``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
2746 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
2747 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
2748 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
2749
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2750 @cindex Buffer, history of word
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2751 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
2752 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
2753 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
2754 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
2755 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
2756 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
2757 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
2758 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
2759 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
2760 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
2761 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
2762 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
2763 and cultural center in its own right.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2764
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2765 Not all buffers are associated with files. For example, a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2766 @file{*scratch*} buffer does not visit any file. Similarly, a
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2767 @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
2768
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2769 In the old days, when you lacked a @file{~/.emacs} file and started an
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2770 Emacs session by typing the command @code{emacs} alone, without naming
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2771 any files, Emacs started with the @file{*scratch*} buffer visible.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2772 Nowadays, you will see a splash screen. You can follow one of the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2773 commands suggested on the splash screen, visit a file, or press the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2774 spacebar to reach the @file{*scratch*} buffer.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2775
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2776 If you switch to the @file{*scratch*} buffer, type
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2777 @code{(buffer-name)}, position the cursor after it, and then type
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2778 @kbd{C-x C-e} to evaluate the expression. The name @code{"*scratch*"}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2779 will be returned and will appear in the echo area. @code{"*scratch*"}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2780 is the name of the buffer. When you type @code{(buffer-file-name)} in
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2781 the @file{*scratch*} buffer and evaluate that, @code{nil} will appear
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2782 in the echo area, just as it does when you evaluate
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2783 @code{(buffer-file-name)} in Info.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2784
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2785 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
2786 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
2787 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
2788 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
2789 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
2790
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2791 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2792 (buffer-name)"*scratch*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2793 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2794
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2795 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2796 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
2797 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
2798 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
2799 this book), this feature is very useful.
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 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
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 Getting Buffers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2804 @findex current-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2805 @findex other-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2806 @cindex Getting 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{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
2809 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
2810 @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
2811 you get is the buffer itself.
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 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
2814 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
2815 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
2816 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
2817 @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
2818 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
2819 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
2820 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
2821 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
2822 @code{current-buffer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2823
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2824 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
2825 @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
2826 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
2827 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
2828 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
2829 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
2830 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
2831
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2832 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2833 Here is an expression containing the function:
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 (current-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
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2840 If you evaluate this expression in Info in Emacs in the usual way,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2841 @file{#<buffer *info*>} will appear in the echo area. The special
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2842 format indicates that the buffer itself is being returned, rather than
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2843 just its name.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2844
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2845 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
2846 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
2847 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
2848
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2849 A related function is @code{other-buffer}. This returns the most
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2850 recently selected buffer other than the one you are in currently, not
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2851 a printed representation of its name. If you have recently switched
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2852 back and forth from the @file{*scratch*} buffer, @code{other-buffer}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2853 will return that buffer.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2854
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2855 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2856 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
2857
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2858 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2859 (other-buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2860 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2861
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2862 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2863 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
2864 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
2865 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
2866 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
2867 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
2868 subtlety that I often forget.}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2869
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2870 @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
2871 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2872 @section Switching Buffers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2873 @findex switch-to-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2874 @findex set-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2875 @cindex Switching to a buffer
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 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
2878 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
2879 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
2880 different buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2881
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2882 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
2883 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
2884 @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
2885 likely typed @kbd{C-x b} and then typed @file{*scratch*}@footnote{Or
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2886 rather, to save typing, you probably only typed @kbd{RET} if the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2887 default buffer was @file{*scratch*}, or if it was different, then you
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2888 typed just part of the name, such as @code{*sc}, pressed your
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2889 @kbd{TAB} key to cause it to expand to the full name, and then typed
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2890 your @kbd{RET} key.} when prompted in the minibuffer for the name of
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2891 the buffer to which you wanted to switch. The keystrokes, @kbd{C-x
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
2892 b}, cause the Lisp interpreter to evaluate the interactive function
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2893 @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
2894 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
2895 @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
2896 @code{forward-sentence}, and so on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2897
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2898 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
2899 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
2900 does.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2901
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2902 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2903 Here is the Lisp expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2904
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2905 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2906 (switch-to-buffer (other-buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2907 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2908
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2909 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2910 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
2911 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
2912 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
2913 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
2914 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
2915 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
2916 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
2917 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
2918 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
2919 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
2920 (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
2921 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
2922 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
2923 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
2924 following more complex expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2925
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2926 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2927 (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
2928 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2929
42562
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
2930 @c noindent
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2931 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
2932 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
2933 @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
2934 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
2935 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
2936 to go to another visible buffer.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2937
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2938 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
2939 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
2940 @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
2941 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
2942 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
2943 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
2944 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
2945 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
2946
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2947 @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
2948 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
2949 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
2950 @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
2951 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
2952 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
2953 there until the command finishes running).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2954
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2955 @cindex @samp{call} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2956 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
2957 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
2958 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
2959 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
2960 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
2961 or her.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2962
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2963 @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
2964 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2965 @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
2966 @cindex Size of buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2967 @cindex Buffer size
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2968 @cindex Point location
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2969 @cindex Location of point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2970
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2971 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
2972 @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
2973 @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
2974 the location of point within it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2975
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2976 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
2977 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
2978 characters in the buffer.
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2981 (buffer-size)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2982 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2983
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2984 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2985 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
2986 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
2987
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2988 @cindex @samp{point} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2989 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
2990 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
2991 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
2992 beginning of the buffer up to point.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2993
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2994 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2995 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
2996 the following expression in the usual way:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2997
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2998 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2999 (point)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3000 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3001
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3002 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3003 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
3004 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
3005 book.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3006
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3007 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3008 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
3009 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
3010
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3011 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3012 (point)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3013 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3016 For me, the value of point in this location is 66043, which means that
73680
a171b46b168c Replace 22.0.100 with 22.1.100.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73619
diff changeset
3017 there are 319 characters (including spaces) between the two
a171b46b168c Replace 22.0.100 with 22.1.100.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73619
diff changeset
3018 expressions. (Doubtless, you will see different numbers, since I will
a171b46b168c Replace 22.0.100 with 22.1.100.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73619
diff changeset
3019 have edited this since I first evaluated point.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3020
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3021 @cindex @samp{narrowing} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3022 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
3023 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
3024 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
3025 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
3026 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
3027 @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
3028 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
3029 value of point in the current buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3030
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3031 @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
3032 @section Exercise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3033
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3034 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
3035 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
3036
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3037 @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
3038 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3039 @chapter How To Write Function Definitions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3040 @cindex Definition writing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3041 @cindex Function definition writing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3042 @cindex Writing a function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3043
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3044 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
3045 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
3046 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
3047 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
3048 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
3049 (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
3050 symbol refers to it.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3051
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3052 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3053 * Primitive Functions::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
3054 * defun:: The @code{defun} special form.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
3055 * Install:: Install a function definition.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
3056 * Interactive:: Making a function interactive.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
3057 * Interactive Options:: Different options for @code{interactive}.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
3058 * Permanent Installation:: Installing code permanently.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
3059 * let:: Creating and initializing local variables.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
3060 * if:: What if?
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
3061 * else:: If--then--else expressions.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
3062 * Truth & Falsehood:: What Lisp considers false and true.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
3063 * save-excursion:: Keeping track of point, mark, and buffer.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3064 * Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3065 * defun Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3066 @end menu
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 @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
3069 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3070 @unnumberedsec An Aside about Primitive Functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3071 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3072 @cindex Primitive functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3073 @cindex Functions, primitive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3074
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3075 @cindex C language primitives
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3076 @cindex Primitives written in C
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3077 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
3078 @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
3079 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
3080 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
3081 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
3082 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
3083 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
3084 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
3085 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
3086
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3087 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
3088 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
3089 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
3090 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
3091 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
3092 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
3093
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3094 @node defun, Install, Primitive Functions, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3095 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3096 @section The @code{defun} Special Form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3097 @findex defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3098 @cindex Special form of @code{defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3099
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3100 @cindex @samp{function definition} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3101 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
3102 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
3103 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
3104 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
3105 (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
3106 @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
3107 called a @dfn{special form}.
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 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
3110 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
3111 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
3112 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
3113 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
3114 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
3115 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
3116 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
3117
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3118 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
3119 @code{defun}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3120
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3121 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3122 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3123 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
3124 attached.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3125
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3126 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3127 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
3128 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
3129 @code{()}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3130
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3131 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3132 Documentation describing the function. (Technically optional, but
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3133 strongly recommended.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3134
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3135 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3136 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
3137 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
3138 typing an appropriate key or keychord.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3139
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3140 @cindex @samp{body} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3141 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3142 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
3143 function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3144 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3145
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3146 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
3147 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
3148
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3149 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3150 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3151 (defun @var{function-name} (@var{arguments}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3152 "@var{optional-documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3153 (interactive @var{argument-passing-info}) ; @r{optional}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3154 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3155 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3156 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3157
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3158 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
3159 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
3160 , Making a Function Interactive}, for that information.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3161
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3162 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3163 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3164 (defun multiply-by-seven (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3165 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3166 (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3167 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3168 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3169
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3170 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
3171 followed by the name of the function.
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 @cindex @samp{argument list} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3174 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
3175 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
3176 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
3177 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
3178 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
3179 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3180
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3181 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
3182 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
3183 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
3184 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
3185 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
3186 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
3187 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
3188 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
3189 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
3190 the function clear.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3191
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3192 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
3193 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
3194 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
3195 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
3196 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
3197 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
3198 `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
3199 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
3200 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
3201 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
3202 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
3203 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
3204
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3205 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3206 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
3207 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
3208 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
3209 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
3210 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
3211 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
3212 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
3213 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
3214 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
3215 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
3216 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
3217 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
3218 @end ignore
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 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
3221 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
3222 @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
3223 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
3224 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
3225 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
3226 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
3227 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
3228 (@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
3229 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
3230 write.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3231
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3232 @findex * @r{(multiplication)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3233 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
3234 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
3235 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
3236 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
3237 @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
3238 function for addition.)
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 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
3241 @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
3242 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
3243 to evaluate this yet!
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3250 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
3251 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
3252 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
3253 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
3254 @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
3255 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
3256 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
3257 definition begins.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3258
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3259 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
3260 (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
3261 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
3262 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
3263 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
3264 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
3265 section.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3266
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3267 @node Install, Interactive, defun, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3268 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3269 @section Install a Function Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3270 @cindex Install a Function Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3271 @cindex Definition installation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3272 @cindex Function definition installation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3273
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3274 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
3275 @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
3276 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
3277 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
3278 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
3279 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
3280 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
3281 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
3282 action installs the function definition.
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)
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 (* 7 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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3293 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
3294 @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
3295 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
3296 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
3297 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
3298 @ref{Permanent Installation, , Installing Code Permanently}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3299
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3300 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3301 * Effect of installation::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
3302 * Change a defun:: How to change a function definition.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3303 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3304
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3305 @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
3306 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3307 @unnumberedsubsec The effect of installation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3308 @end ifnottex
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 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
3311 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
3312 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
3313 echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3314
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3315 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3316 (multiply-by-seven 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3317 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3318
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3319 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
3320 @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
3321 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
3322 @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
3323
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3324 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3325 @group
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3326 multiply-by-seven is a Lisp function.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3327 (multiply-by-seven NUMBER)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3328
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3329 Multiply NUMBER by seven.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3330 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3331 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3332
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3333 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3334 (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
3335
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3336 @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
3337 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3338 @subsection Change a Function Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3339 @cindex Changing a function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3340 @cindex Function definition, how to change
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3341 @cindex Definition, how to change
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3342
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3343 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
3344 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
3345 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
3346 very simple.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3347
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3348 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
3349 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
3350 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
3351 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
3352 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
3353 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
3354 version''.
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3357 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3358 (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
3359 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3360 (+ number number number number number number number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3361 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3362 @end smallexample
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 @cindex Comments in Lisp code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3365 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
3366 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
3367 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
3368 each line with a semicolon.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3369
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3370 @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
3371 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
3372 Reference Manual}, for more about comments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3373
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3374 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
3375 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
3376 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
3377
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3378 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
3379 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
3380 install it again.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3381
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3382 @node Interactive, Interactive Options, Install, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3383 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3384 @section Make a Function Interactive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3385 @cindex Interactive functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3386 @findex interactive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3387
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3388 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
3389 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
3390 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
3391 @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
3392 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
3393 @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
3394
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3395 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
3396 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
3397 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
3398 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
3399 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
3400 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
3401
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3402 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
3403 * Interactive multiply-by-seven:: An overview.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
3404 * multiply-by-seven in detail:: The interactive version.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3405 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3406
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3407 @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
3408 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3409 @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
3410 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3411
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3412 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
3413 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
3414 interactive version of @code{multiply-by-seven}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3415
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3416 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3417 Here is the code:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3418
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3419 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3420 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3421 (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
3422 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3423 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3424 (message "The result is %d" (* 7 number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3425 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3426 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3427
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3428 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3429 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
3430 @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
3431 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
3432 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
3433 @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
3434 echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3435
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3436 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
3437 ways:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3438
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3439 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3440 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3441 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
3442 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
3443 @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
3444
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3445 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3446 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
3447 @kbd{C-u 3 M-e}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3448 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3449
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3450 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3451 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
3452 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
3453 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
3454
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3455 (@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
3456 to a key.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3457
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3458 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
3459 @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
3460 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
3461 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
3462
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3463 @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
3464 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3465 @subsection An Interactive @code{multiply-by-seven}
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 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
3468 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
3469 @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
3470 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3471
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3472 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3473 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3474 (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
3475 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3476 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3477 (message "The result is %d" (* 7 number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3478 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3479 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3480
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3481 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
3482 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
3483 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
3484
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3485 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3486 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
3487 @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
3488
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3489 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3490 (message "The result is %d" (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3491 @end smallexample
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3494 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3495 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
3496 evaluate the line as if it were:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3497
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3498 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3499 (message "The result is %d" (* 7 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3500 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3501
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3502 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3503 (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
3504 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
3505 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
3506 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
3507 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
3508
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3509 As we have seen, @code{message} is an Emacs Lisp function especially
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3510 designed for sending a one line message to a user. (@xref{message, ,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3511 The @code{message} function}.) In summary, the @code{message}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3512 function prints its first argument in the echo area as is, except for
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3513 occurrences of @samp{%d} or @samp{%s} (and various other %-sequences
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3514 which we have not mentioned). When it sees a control sequence, the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3515 function looks to the second or subsequent arguments and prints the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3516 value of the argument in the location in the string where the control
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3517 sequence is located.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3518
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3519 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
3520 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
3521 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
3522 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
3523 is 35}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3524
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3525 (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
3526 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
3527 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
3528 @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
3529 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
3530 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
3531 quotes.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3532
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3533 @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
3534 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3535 @section Different Options for @code{interactive}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3536 @cindex Options for @code{interactive}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3537 @cindex Interactive options
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3538
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3539 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
3540 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
3541 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
3542 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
3543 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
3544 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
3545 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
3546 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
3547 @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
3548
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3549 @need 1250
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3550 Consider the function @code{zap-to-char}. Its interactive expression
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3551 is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3552
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3553 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3554 (interactive "p\ncZap to char: ")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3555 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3556
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3557 The first part of the argument to @code{interactive} is @samp{p}, with
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3558 which you are already familiar. This argument tells Emacs to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3559 interpret a `prefix', as a number to be passed to the function. You
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3560 can specify a prefix either by typing @kbd{C-u} followed by a number
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3561 or by typing @key{META} followed by a number. The prefix is the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3562 number of specified characters. Thus, if your prefix is three and the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3563 specified character is @samp{x}, then you will delete all the text up
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3564 to and including the third next @samp{x}. If you do not set a prefix,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3565 then you delete all the text up to and including the specified
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3566 character, but no more.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3567
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3568 The @samp{c} tells the function the name of the character to which to delete.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3569
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3570 More formally, a function with two or more arguments can have
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3571 information passed to each argument by adding parts to the string that
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3572 follows @code{interactive}. When you do this, the information is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3573 passed to each argument in the same order it is specified in the
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3574 @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
3575 the next part by a @samp{\n}, which is a newline. For example, you
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3576 can follow @samp{p} with a @samp{\n} and an @samp{cZap to char:@: }.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3577 This causes Emacs to pass the value of the prefix argument (if there
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3578 is one) and the character.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3579
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3580 In this case, the function definition looks like the following, where
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3581 @code{arg} and @code{char} are the symbols to which @code{interactive}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3582 binds the prefix argument and the specified character:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3583
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3584 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3585 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3586 (defun @var{name-of-function} (arg char)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3587 "@var{documentation}@dots{}"
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3588 (interactive "p\ncZap to char: ")
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3589 @var{body-of-function}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3590 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3591 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3592
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3593 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3594 (The space after the colon in the prompt makes it look better when you
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3595 are prompted. @xref{copy-to-buffer, , The Definition of
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3596 @code{copy-to-buffer}}, for an example.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3597
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3598 When a function does not take arguments, @code{interactive} does not
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3599 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
3600 @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
3601 this.
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 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
3604 application, you can pass your own arguments to @code{interactive} as
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3605 a list.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3606
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3607 @xref{append-to-buffer, , The Definition of @code{append-to-buffer}},
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3608 for an example. @xref{Using Interactive, , Using @code{Interactive},
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3609 elisp, The GNU Emacs Lisp Reference Manual}, for a more complete
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3610 explanation about this technique.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3611
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3612 @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
3613 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3614 @section Install Code Permanently
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3615 @cindex Install code permanently
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3616 @cindex Permanent code installation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3617 @cindex Code installation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3618
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3619 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
3620 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
3621 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
3622 function definition again.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3623
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3624 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
3625 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
3626 doing this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3627
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3628 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3629 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3630 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
3631 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
3632 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
3633 the function definitions within it are installed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3634 @xref{Emacs Initialization, , Your @file{.emacs} File}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3635
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3636 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3637 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
3638 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
3639 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
3640 functions in the files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3641 @xref{Loading Files, , Loading Files}.
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 @item
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3644 Thirdly, if you have code that your whole site will use, it is usual
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3645 to put it in a file called @file{site-init.el} that is loaded when
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3646 Emacs is built. This makes the code available to everyone who uses
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3647 your machine. (See the @file{INSTALL} file that is part of the Emacs
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3648 distribution.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3649 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3650
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3651 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
3652 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
3653 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
3654 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
3655 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
3656 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
3657 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
3658 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
3659 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
3660
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3661 @node let, if, Permanent Installation, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3662 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3663 @section @code{let}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3664 @findex let
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3665
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3666 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
3667 to use in most function definitions.
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 @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
3670 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
3671 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
3672
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3673 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
3674 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
3675 `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
3676 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
3677 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
3678 different house.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3679
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3680 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
3681 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
3682 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
3683 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
3684 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
3685 @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
3686
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3687 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3688 * Prevent confusion::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3689 * Parts of let Expression::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3690 * Sample let Expression::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3691 * Uninitialized let Variables::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3692 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3693
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3694 @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
3695 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3696 @unnumberedsubsec @code{let} Prevents Confusion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3697 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3698
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3699 @cindex @samp{local variable} defined
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3700 @cindex @samp{variable, local}, defined
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3701 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
3702 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
3703 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
3704 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
3705 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
3706 @xref{defun, , The @code{defun} Special Form}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3707
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3708 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
3709 @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
3710 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
3711 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
3712
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3713 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
3714 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
3715 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
3716 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
3717 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
3718 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
3719 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
3720
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3721 @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
3722 @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
3723 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
3724 `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
3725 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
3726 @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
3727 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
3728 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
3729 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
3730 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
3731 `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
3732
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3733 @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
3734 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3735 @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
3736 @cindex @code{let} expression, parts of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3737 @cindex Parts of @code{let} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3738
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3739 @cindex @samp{varlist} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3740 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
3741 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
3742 @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
3743 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
3744 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
3745 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
3746
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3747 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3748 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
3749
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3750 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3751 (let @var{varlist} @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3752 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3753
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3754 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3755 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
3756 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
3757 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
3758 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
3759 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
3760
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3761 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
3762 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
3763 @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
3764 @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
3765
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3766 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
3767 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
3768 template.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3769
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3770 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
3771 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
3772
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3773 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3774 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3775 (let ((@var{variable} @var{value})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3776 (@var{variable} @var{value})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3777 @dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3778 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3779 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3780 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3781
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3782 @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
3783 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3784 @subsection Sample @code{let} Expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3785 @cindex Sample @code{let} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3786 @cindex @code{let} expression sample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3787
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3788 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
3789 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
3790 @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
3791
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3792 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3793 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3794 (let ((zebra 'stripes)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3795 (tiger 'fierce))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3796 (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
3797 zebra tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3798 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3799 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3801 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
3802
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3803 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
3804 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
3805 element of its two-element list. In the varlist, Emacs binds the
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3806 variable @code{zebra} to the value @code{stripes}@footnote{According
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3807 to Jared Diamond in @cite{Guns, Germs, and Steel}, ``@dots{} zebras
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3808 become impossibly dangerous as they grow older'' but the claim here is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3809 that they do not become fierce like a tiger. (1997, W. W. Norton and
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3810 Co., ISBN 0-393-03894-2, page 171)}, and binds the
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3811 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
3812 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
3813 well have been another list or a string. The body of the @code{let}
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3814 follows after the list holding the variables. In this example, the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3815 body is a list that uses the @code{message} function to print a string
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
3816 in the echo area.
41421
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 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3819 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
3820 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
3821 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
3822
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3823 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3824 "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
3825 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3826
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3827 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
3828 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
3829 @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
3830 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
3831 second @samp{%s}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3832
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3833 @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
3834 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3835 @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
3836 @cindex Uninitialized @code{let} variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3837 @cindex @code{let} variables uninitialized
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3838
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3839 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
3840 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
3841 @code{nil}, as in the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3842
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3843 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3844 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3845 (let ((birch 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3846 pine
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3847 fir
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3848 (oak 'some))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3849 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3850 "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
3851 birch pine fir oak))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3852 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3853 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3854
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3855 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3856 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
3857
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3858 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3859 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
3860 appear in your echo area:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3861
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3862 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3863 "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
3864 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3865
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3866 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3867 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
3868 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
3869 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
3870
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3871 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
3872 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
3873 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
3874 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
3875 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
3876 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
3877 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
3878 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
3879 @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
3880 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
3881
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3882 @node if, else, let, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3883 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3884 @section The @code{if} Special Form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3885 @findex if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3886 @cindex Conditional with @code{if}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3887
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3888 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
3889 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
3890 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
3891 @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
3892 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
3893 function @code{beginning-of-buffer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3894
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3895 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
3896 @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
3897 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
3898 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
3899
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3900 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3901 * if in more detail::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
3902 * type-of-animal in detail:: An example of an @code{if} expression.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3903 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3904
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3905 @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
3906 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3907 @unnumberedsubsec @code{if} in more detail
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3908 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3909
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3910 @cindex @samp{if-part} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3911 @cindex @samp{then-part} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3912 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
3913 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
3914 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
3915 @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
3916 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
3917
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3918 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
3919 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
3920 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
3921 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
3922 expression easier to read.
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3925 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3926 (if @var{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3927 @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
3928 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3929 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3930
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3931 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3932 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
3933 is evaluated by the Lisp interpreter.
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 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
3936 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
3937 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
3938
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3939 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3940 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3941 (if (> 5 4) ; @r{if-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3942 (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
3943 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3944 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3945
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3946 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3947 (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
3948 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
3949 @findex > (greater than)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3950
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3951 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
3952 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
3953 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
3954 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
3955 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
3956
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3957 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
3958 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
3959 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
3960 @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
3961 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
3962
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3963 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3964 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3965 (defun type-of-animal (characteristic)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3966 "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
3967 If the CHARACTERISTIC is the symbol `fierce',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3968 then warn of a tiger."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3969 (if (equal characteristic 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3970 (message "It's a tiger!")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3971 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3972 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3973
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3974 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3975 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3976 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
3977 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
3978 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
3979
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3980 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3981 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3982 (type-of-animal 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3983
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3984 (type-of-animal 'zebra)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3985
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3986 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3987 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3988
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3989 @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
3990 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3991 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
3992 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
3993 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
3994 printed in the echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3995
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3996 @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
3997 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3998 @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
3999
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4000 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
4001
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4002 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
4003 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
4004 a second for an @code{if} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4005
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4006 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4007 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
4008
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4009 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4010 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4011 (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
4012 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4013 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4014 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4015 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4016
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4017 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4018 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
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 (defun type-of-animal (characteristic)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4023 "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
4024 If the CHARACTERISTIC is the symbol `fierce',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4025 then warn of a tiger."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4026 @var{body: the} @code{if} @var{expression})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4027 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4028 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4029
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4030 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
4031 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
4032 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
4033 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
4034 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
4035 consists of the @code{if} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4036
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4037 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4038 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
4039
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4040 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4041 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4042 (if @var{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4043 @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
4044 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4045 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4046
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4047 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4048 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
4049 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4050
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4051 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4052 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4053 (if (equal characteristic 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4054 (message "It's a tiger!")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4055 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4056 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4057
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4058 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4059 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
4060
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4061 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4062 (equal characteristic 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4063 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4064
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4065 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4066 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
4067 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
4068 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
4069 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
4070 this function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4071
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4072 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
4073 @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
4074 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
4075 '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
4076 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
4077 @code{(message "It's tiger!")}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4078
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4079 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
4080 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
4081 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
4082 @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
4083
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4084 @node else, Truth & Falsehood, if, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4085 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4086 @section If--then--else Expressions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4087 @cindex Else
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4088
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4089 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
4090 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
4091 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
4092 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
4093 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
4094 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
4095 the beach, else read a book!''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4096
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4097 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
4098 @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
4099 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
4100 indented less than the then-part:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4101
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4102 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4103 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4104 (if @var{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4105 @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
4106 @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
4107 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4108 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4109
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4110 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
4111 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
4112
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4113 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4114 @group
75542
5325e1fc379d (else): Rephrase message of first if-then-else example so it is right
Robert J. Chassell <bob@rattlesnake.com>
parents: 75348
diff changeset
4115 (if (> 4 5) ; @r{if-part}
5325e1fc379d (else): Rephrase message of first if-then-else example so it is right
Robert J. Chassell <bob@rattlesnake.com>
parents: 75348
diff changeset
4116 (message "4 falsely greater than 5!") ; @r{then-part}
5325e1fc379d (else): Rephrase message of first if-then-else example so it is right
Robert J. Chassell <bob@rattlesnake.com>
parents: 75348
diff changeset
4117 (message "4 is not greater than 5!")) ; @r{else-part}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4118 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4119 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4120
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4121 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4122 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
4123 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
4124 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
4125 @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
4126
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4127 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
4128 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
4129 expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4130
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4131 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4132 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
4133 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
4134 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
4135 arguments to the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4136
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4137 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4138 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4139 (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
4140 "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
4141 If the CHARACTERISTIC is the symbol `fierce',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4142 then warn of a tiger;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4143 else say it's not fierce."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4144 (if (equal characteristic 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4145 (message "It's a tiger!")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4146 (message "It's not fierce!")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4147 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4148 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4149 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4151 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4152 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4153 (type-of-animal 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4154
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4155 (type-of-animal 'zebra)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4156
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4157 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4158 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4159
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4160 @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
4161 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4162 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
4163 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
4164 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
4165 @code{"It's not fierce!"}.
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 (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
4168 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
4169 misleading! When you write code, you need to take into account the
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4170 possibility that some such argument will be tested by the @code{if}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4171 and write your program accordingly.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4172
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4173 @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
4174 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4175 @section Truth and Falsehood in Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4176 @cindex Truth and falsehood in Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4177 @cindex Falsehood and truth in Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4178 @findex nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4179
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4180 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
4181 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
4182 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
4183 `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
4184 at all---is `true'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4185
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4186 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
4187 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
4188 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
4189 returned is a number such as 47, a string such as @code{"hello"}, or a
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4190 symbol (other than @code{nil}) such as @code{flowers}, or a list (so
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4191 long as it is not empty), or even a buffer!
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4192
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4193 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
4194 * nil explained:: @code{nil} has two meanings.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4195 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4196
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4197 @node nil explained, , Truth & Falsehood, Truth & Falsehood
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4198 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4199 @unnumberedsubsec An explanation of @code{nil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4200 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4201
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4202 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
4203
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4204 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
4205 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
4206 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
4207 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
4208 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
4209 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
4210
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4211 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
4212 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
4213 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
4214 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
4215 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
4216 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
4217 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
4218 list, is returned by evaluating the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4219
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4220 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
4221
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4222 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
4223 @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
4224 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
4225 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
4226 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
4227 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
4228
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4229 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4230 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4231 (if 4
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4232 'true
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4233 'false)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4234 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4235
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4236 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4237 (if nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4238 'true
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4239 'false)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4240 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4241 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4242
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4243 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4244 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
4245 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
4246 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
4247 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
4248
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4249 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4250 (> 5 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4251 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4252
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4253 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4254 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4255 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
4256
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4257 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4258 (> 4 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4259 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4260
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4261 @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
4262 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4263 @section @code{save-excursion}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4264 @findex save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4265 @cindex Region, what it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4266 @cindex Preserving point, mark, and buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4267 @cindex Point, mark, buffer preservation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4268 @findex point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4269 @findex mark
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4270
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4271 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
4272 that we will discuss in this chapter.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4273
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4274 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
4275 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
4276 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
4277 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
4278 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
4279 unexpected movement of point or mark.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4280
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4281 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
4282 * Point and mark:: A review of various locations.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4283 * Template for save-excursion::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4284 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4285
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4286 @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
4287 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4288 @unnumberedsubsec Point and Mark
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4289 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4290
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4291 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
4292 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
4293 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
4294 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
4295 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
4296 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
4297 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
4298 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
4299 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
4300
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4301 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
4302 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
4303 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
4304 (@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
4305 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
4306 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
4307 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
4308 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
4309 times.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4310
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4311 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
4312 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
4313 @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
4314 @code{print-region}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4315
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4316 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
4317 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
4318 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
4319 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
4320 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
4321 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
4322 evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4323
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4324 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
4325 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
4326 @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
4327 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
4328 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
4329 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
4330 @code{save-excursion} is good housekeeping.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4331
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4332 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
4333 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
4334 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
4335 abnormal exit''). This feature is very helpful.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4336
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4337 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
4338 @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
4339 it, too. This means you can write code that will change the buffer and
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4340 have @code{save-excursion} switch you back to the original buffer.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4341 This is how @code{save-excursion} is used in @code{append-to-buffer}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4342 (@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
4343
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4344 @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
4345 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4346 @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
4347
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4348 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4349 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
4350
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4351 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4352 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4353 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4354 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4355 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4356 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4357
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4358 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4359 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
4360 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
4361 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
4362 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
4363 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
4364 @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
4365 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
4366
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4367 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4368 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
4369 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4370
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4371 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4372 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4373 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4374 @var{first-expression-in-body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4375 @var{second-expression-in-body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4376 @var{third-expression-in-body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4377 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4378 @var{last-expression-in-body})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4379 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4380 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4381
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4382 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4383 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
4384
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4385 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
4386 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
4387
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4388 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4389 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4390 (let @var{varlist}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4391 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4392 @var{body}@dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4393 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4394 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4395
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4396 @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
4397 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4398 @section Review
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4399
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4400 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
4401 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
4402 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
4403
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4404 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4405 @item eval-last-sexp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4406 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
4407 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
4408 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
4409 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
4410
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4411 @item defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4412 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
4413 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
4414 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
4415 definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4416
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4417 @need 1250
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4418 For example, in an early version of Emacs, the function definition was
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4419 as follows. (It is slightly more complex now that it seeks the first
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4420 non-whitespace character rather than the first visible character.)
41421
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4423 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4424 (defun back-to-indentation ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4425 "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
4426 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4427 (beginning-of-line 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4428 (skip-chars-forward " \t"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4429 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4430 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4431
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4432 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4433 In GNU Emacs 22,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4434
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4435 (defun backward-to-indentation (&optional arg)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4436 "Move backward ARG lines and position at first nonblank character."
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4437 (interactive "p")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4438 (forward-line (- (or arg 1)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4439 (skip-chars-forward " \t"))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4440
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4441 (defun back-to-indentation ()
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4442 "Move point to the first non-whitespace character on this line."
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4443 (interactive)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4444 (beginning-of-line 1)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4445 (skip-syntax-forward " " (line-end-position))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4446 ;; Move back over chars that have whitespace syntax but have the p flag.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4447 (backward-prefix-chars))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4448 @end ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4449
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4450 @item interactive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4451 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
4452 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
4453 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
4454 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
4455 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
4456 newlines, @samp{\n}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4457
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
4458 @need 1000
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4459 Common code characters are:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4460
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4461 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4462 @item b
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4463 The name of an existing buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4464
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4465 @item f
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4466 The name of an existing file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4467
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4468 @item p
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4469 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
4470
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4471 @item r
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4472 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
4473 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
4474 rather than one.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4475 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4476
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4477 @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
4478 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
4479 code characters.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4480
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4481 @item let
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4482 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
4483 @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
4484 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
4485 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
4486 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
4487 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
4488 @code{let}.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4491 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4492
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4493 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4494 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4495 (let ((foo (buffer-name))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4496 (bar (buffer-size)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4497 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4498 "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
4499 foo bar))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4500 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4501 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4502
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4503 @item save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4504 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
4505 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
4506 and mark and buffer afterward.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4507
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4508 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4509 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4510
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4511 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4512 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4513 (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
4514 (- (point)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4515 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4516 (goto-char (point-min)) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4517 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4518 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4519
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4520 @item if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4521 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
4522 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
4523
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4524 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
4525 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
4526 commonly used.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4527
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4528 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4529 For example,
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4532 @group
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
4533 (if (= 22 emacs-major-version)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4534 (message "This is version 22 Emacs")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4535 (message "This is not version 22 Emacs"))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4536 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4537 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4538
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4539 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4540 @item <
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4541 @itemx >
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4542 @itemx <=
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4543 @itemx >=
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4544 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
4545 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
4546 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
4547 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
4548 @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
4549 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
4550 (markers indicate positions in buffers).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4551
73680
a171b46b168c Replace 22.0.100 with 22.1.100.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73619
diff changeset
4552 @need 800
73597
4d65d5858190 * emacs-lisp-intro.texi: Remove version reference for X colors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73587
diff changeset
4553 @item =
73680
a171b46b168c Replace 22.0.100 with 22.1.100.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73619
diff changeset
4554 The @code{=} function tests whether two arguments, both numbers or
73597
4d65d5858190 * emacs-lisp-intro.texi: Remove version reference for X colors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73587
diff changeset
4555 markers, are equal.
4d65d5858190 * emacs-lisp-intro.texi: Remove version reference for X colors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73587
diff changeset
4556
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
4557 @need 1250
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
4558 @item equal
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
4559 @itemx eq
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
4560 Test whether two objects are the same. @code{equal} uses one meaning
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
4561 of the word `same' and @code{eq} uses another: @code{equal} returns
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
4562 true if the two objects have a similar structure and contents, such as
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
4563 two copies of the same book. On the other hand, @code{eq}, returns
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
4564 true if both arguments are actually the same object.
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
4565 @findex equal
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
4566 @findex eq
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
4567
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
4568 @need 1250
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4569 @item string<
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4570 @itemx string-lessp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4571 @itemx string=
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4572 @itemx string-equal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4573 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
4574 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
4575 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
4576
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4577 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
4578 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
4579 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
4580
42109
24f8e84cb04d Indexed `empty string' definition.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42108
diff changeset
4581 @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
4582 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
4583 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
4584
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4585 @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
4586 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
4587 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
4588
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4589 @item message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4590 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
4591 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
4592 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
4593 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
4594 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
4595 number; it will be printed as the character with that @sc{ascii} code.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4596 (Various other %-sequences have not been mentioned.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4597
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4598 @item setq
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4599 @itemx set
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4600 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
4601 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
4602 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
4603 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
4604 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
4605 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
4606
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4607 @item buffer-name
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4608 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
4609
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4610 @itemx buffer-file-name
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4611 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
4612 visiting.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4613
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4614 @item current-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4615 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
4616 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
4617
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4618 @item other-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4619 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
4620 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
4621 buffer).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4622
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4623 @item switch-to-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4624 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
4625 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
4626
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4627 @item set-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4628 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
4629 alter what the window is showing.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4630
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4631 @item buffer-size
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4632 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
4633
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4634 @item point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4635 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
4636 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
4637 buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4638
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4639 @item point-min
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4640 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
4641 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
4642
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4643 @item point-max
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4644 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
4645 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
4646 effect.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4647 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4648
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4649 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4650 @node defun Exercises, , Review, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4651 @section Exercises
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4652
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4653 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4654 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4655 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
4656 argument, a number. Make that function interactive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4657
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4658 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4659 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
4660 @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
4661 and if so, prints an appropriate message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4662 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4663
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4664 @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
4665 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4666 @chapter A Few Buffer--Related Functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4667
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4668 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
4669 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
4670 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
4671 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
4672 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
4673 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
4674 buffers. Later, we will study other functions.
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 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
4677 * Finding More:: How to find more information.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
4678 * simplified-beginning-of-buffer:: Shows @code{goto-char},
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
4679 @code{point-min}, and @code{push-mark}.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
4680 * mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
4681 * append-to-buffer:: Uses @code{save-excursion} and
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
4682 @code{insert-buffer-substring}.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
4683 * Buffer Related Review:: Review.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4684 * Buffer Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4685 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4686
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4687 @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
4688 @section Finding More Information
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4690 @findex describe-function, @r{introduced}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4691 @cindex Find function documentation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4692 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
4693 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
4694 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
4695 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
4696 @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
4697 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
4698 then @key{RET}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4699
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4700 @cindex Find source of function
73680
a171b46b168c Replace 22.0.100 with 22.1.100.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73619
diff changeset
4701 @c In version 22, tells location both of C and of Emacs Lisp
a171b46b168c Replace 22.0.100 with 22.1.100.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73619
diff changeset
4702 Also, @code{describe-function} will tell you the location of the
a171b46b168c Replace 22.0.100 with 22.1.100.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73619
diff changeset
4703 function definition.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4704
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4705 Put point into the name of the file that contains the function and
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4706 press the @key{RET} key. In this case, @key{RET} means
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4707 @code{push-button} rather than `return' or `enter'. Emacs will take
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4708 you directly to the function definition.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4709
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4710 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4711 Not In version 22
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4712
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4713 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
4714 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
4715 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
4716 definition.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4717 @end ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4718
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4719 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
4720 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
4721 @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
4722 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
4723 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
4724 Texinfo source file of this document.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4725 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
4726 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
4727 @code{find-tags} jumps.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4728
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
4729 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
4730 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
4731 @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
4732 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
4733 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
4734 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
4735 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
4736 @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
4737 @key{ALT}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4738
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
4739 @c !!! 22.1.1 tags table location in this paragraph
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4740 @cindex TAGS table, specifying
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4741 @findex find-tags
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4742 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
4743 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
4744 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
4745 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
4746 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
4747 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
4748 @code{M-x visit-tags-table} command and specify a pathname such as
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
4749 @file{/usr/local/share/emacs/22.1.1/lisp/TAGS}. If the tags table
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4750 has not already been created, you will have to create it yourself. It
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4751 will in a file such as @file{/usr/local/src/emacs/src/TAGS}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4752
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4753 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4754 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
4755 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
4756 with @kbd{C-x d} (@code{dired}). Then run the compile command, with
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4757 @w{@code{etags *.el}} as the command to execute:
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4758
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4759 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4760 M-x compile RET etags *.el RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4761 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4762
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4763 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
4764
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4765 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
4766 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
4767 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
4768
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4769 @cindex Library, as term for `file'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4770 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
4771 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
4772 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
4773 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
4774 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
4775 @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
4776 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
4777 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
4778 @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
4779 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
4780 @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
4781 by topic keywords.''
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4782
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4783 @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
4784 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4785 @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
4786 @findex simplified-beginning-of-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4787
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4788 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
4789 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
4790 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
4791 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
4792 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
4793
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4794 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
4795 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
4796 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
4797 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
4798 (@xref{beginning-of-buffer, , Complete Definition of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4799 @code{beginning-of-buffer}}.)
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 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
4802 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
4803 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
4804 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
4805 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
4806 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
4807 of the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4808
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4809 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4810 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
4811
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4812 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4813 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4814 (defun simplified-beginning-of-buffer ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4815 "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
4816 leave mark at previous position."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4817 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4818 (push-mark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4819 (goto-char (point-min)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4820 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4821 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4822
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4823 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
4824 the special form @code{defun}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4825
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4826 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4827 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4828 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
4829
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4830 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4831 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
4832
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4833 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4834 The documentation string.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4835
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4836 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4837 The interactive expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4838
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4839 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4840 The body.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4841 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4842
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4843 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4844 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
4845 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
4846 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
4847 an optional argument.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4848
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4849 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
4850 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
4851 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
4852 require one.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4853
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4854 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4855 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
4856
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4857 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4858 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4859 (push-mark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4860 (goto-char (point-min))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4861 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4862 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4863
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4864 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
4865 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
4866 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
4867 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
4868
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4869 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
4870 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
4871 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
4872 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
4873 Narrowing and Widening}.)
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 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
4876 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
4877 @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
4878 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
4879
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4880 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
4881
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4882 @findex describe-function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4883 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
4884 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
4885 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
4886 @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
4887 @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
4888 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
4889 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
4890
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4891 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4892 @group
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4893 Set point to POSITION, a number or marker.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4894 Beginning of buffer is position (point-min), end is (point-max).
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4895 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4896 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4897
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4898 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4899 The function's one argument is the desired position.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4900
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4901 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4902 (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
4903 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
4904 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
4905 @key{RET}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4906
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4907 The @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
4908 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
4909 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
4910 of @code{(goto-char (point-min))}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4911
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4912 @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
4913 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4914 @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
4915 @findex mark-whole-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4916
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4917 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
4918 @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
4919 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
4920
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4921 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
4922 @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
4923 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
4924 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
4925 h}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4926
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4927 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4928 * mark-whole-buffer overview::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
4929 * Body of mark-whole-buffer:: Only three lines of code.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4930 @end menu
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4931
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4932 @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
4933 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4934 @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
4935 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4936
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4937 @need 1250
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4938 In GNU Emacs 22, the code for the complete function looks like this:
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4939
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4940 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4941 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4942 (defun mark-whole-buffer ()
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4943 "Put point at beginning and mark at end of buffer.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4944 You probably should not use this function in Lisp programs;
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4945 it is usually a mistake for a Lisp function to use any subroutine
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4946 that uses or sets the mark."
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4947 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4948 (push-mark (point))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4949 (push-mark (point-max) nil t)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4950 (goto-char (point-min)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4951 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4952 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4953
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4954 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4955 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
4956 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
4957 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4958
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4959 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4960 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4961 (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
4962 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4963 (@var{interactive-expression}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4964 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4965 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4966 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4967
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4968 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
4969 @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
4970 @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
4971 The documentation comes next.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4972
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4973 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
4974 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
4975 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
4976 previous section.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4977
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
4978 @need 1250
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4979 @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
4980 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4981 @subsection Body of @code{mark-whole-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4982
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4983 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
4984 lines of code:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4985
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4986 @c GNU Emacs 22
41421
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 (push-mark (point))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
4990 (push-mark (point-max) nil t)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4991 (goto-char (point-min))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4992 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4993 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4994
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4995 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
4996
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4997 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
4998 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
4999 @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
5000 at the current position of the cursor.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5001
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5002 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
5003 @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
5004 @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
5005 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
5006 @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
5007 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
5008 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
5009 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
5010 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
5011 there.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5012
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5013 In earlier versions of GNU Emacs, the next line of
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5014 @code{mark-whole-buffer} was @code{(push-mark (point-max))}. This
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5015 expression sets a mark at the point in the buffer that has the highest
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5016 number. This will be the end of the buffer (or, if the buffer is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5017 narrowed, the end of the accessible portion of the buffer.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5018 @xref{Narrowing & Widening, , Narrowing and Widening}, for more about
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5019 narrowing.) After this mark has been set, the previous mark, the one
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5020 set at point, is no longer set, but Emacs remembers its position, just
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5021 as all other recent marks are always remembered. This means that you
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5022 can, if you wish, go back to that position by typing @kbd{C-u
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5023 C-@key{SPC}} twice.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5024
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5025 @need 1250
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5026 In GNU Emacs 22, the @code{(point-max)} is slightly more complicated.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5027 The line reads
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5028
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5029 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5030 (push-mark (point-max) nil t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5031 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5032
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5033 @noindent
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5034 The expression works nearly the same as before. It sets a mark at the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5035 highest numbered place in the buffer that it can. However, in this
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5036 version, @code{push-mark} has two additional arguments. The second
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5037 argument to @code{push-mark} is @code{nil}. This tells the function
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5038 it @emph{should} display a message that says `Mark set' when it pushes
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5039 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
5040 @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
5041 turned on. Transient Mark mode highlights the currently active
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5042 region. It is often turned off.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5043
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5044 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
5045 (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
5046 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
5047 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
5048 (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
5049 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
5050 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
5051 region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5052
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5053 @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
5054 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5055 @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
5056 @findex append-to-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5057
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5058 The @code{append-to-buffer} command is more complex than the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5059 @code{mark-whole-buffer} command. What it does is copy the region
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5060 (that is, the part of the buffer between point and mark) from the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5061 current buffer to a specified buffer.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5062
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5063 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5064 * append-to-buffer overview::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
5065 * append interactive:: A two part interactive expression.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
5066 * append-to-buffer body:: Incorporates a @code{let} expression.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
5067 * append save-excursion:: How the @code{save-excursion} works.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5068 @end menu
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 @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
5071 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5072 @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
5073 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5074
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5075 @findex insert-buffer-substring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5076 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
5077 @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
5078 @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
5079 string of characters from part of a buffer, a ``substring'', and
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5080 inserts them into another buffer.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5081
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5082 Most of @code{append-to-buffer} is
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5083 concerned with setting up the conditions for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5084 @code{insert-buffer-substring} to work: the code must specify both the
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5085 buffer to which the text will go, the window it comes from and goes
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5086 to, and the region that will be copied.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5087
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5088 @need 1250
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5089 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
5090
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5091 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5092 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5093 (defun append-to-buffer (buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5094 "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
5095 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
5096 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5097
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5098 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5099 When calling from a program, give three arguments:
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5100 BUFFER (or buffer name), START and END.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5101 START and END specify the portion of the current buffer to be copied."
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5102 (interactive
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5103 (list (read-buffer "Append to buffer: " (other-buffer
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5104 (current-buffer) t))
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5105 (region-beginning) (region-end)))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5106 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5107 @group
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5108 (let ((oldbuf (current-buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5109 (save-excursion
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5110 (let* ((append-to (get-buffer-create buffer))
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5111 (windows (get-buffer-window-list append-to t t))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5112 point)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5113 (set-buffer append-to)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5114 (setq point (point))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5115 (barf-if-buffer-read-only)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5116 (insert-buffer-substring oldbuf start end)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5117 (dolist (window windows)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5118 (when (= (window-point window) point)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5119 (set-window-point window (point))))))))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5120 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5121 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5122
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5123 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
5124 filled-in templates.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5125
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5126 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
5127 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
5128
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5129 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5130 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5131 (defun append-to-buffer (buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5132 "@var{documentation}@dots{}"
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5133 (interactive @dots{})
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5134 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5135 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5136 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5137
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5138 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
5139 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
5140 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
5141 will be copied.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5142
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5143 The next part of the function is the documentation, which is clear and
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5144 complete. As is conventional, the three arguments are written in
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5145 upper case so you will notice them easily. Even better, they are
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5146 described in the same order as in the argument list.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5147
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5148 Note that the documentation distinguishes between a buffer and its
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5149 name. (The function can handle either.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5151 @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
5152 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5153 @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
5154
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5155 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
5156 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
5157 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
5158 Function Interactive}.) The expression reads as follows:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5159
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5160 @smallexample
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5161 @group
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5162 (interactive
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5163 (list (read-buffer
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5164 "Append to buffer: "
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5165 (other-buffer (current-buffer) t))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5166 (region-beginning)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5167 (region-end)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5168 @end group
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5169 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5170
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5171 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5172 This expression is not one with letters standing for parts, as
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5173 described earlier. Instead, it starts a list with thee parts.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5174
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5175 The first part of the list is an expression to read the name of a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5176 buffer and return it as a string. That is @code{read-buffer}. The
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5177 function requires a prompt as its first argument, @samp{"Append to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5178 buffer: "}. Its second argument tells the command what value to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5179 provide if you don't specify anything.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5180
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5181 In this case that second argument is an expression containing the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5182 function @code{other-buffer}, an exception, and a @samp{t}, standing
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5183 for true.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5184
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5185 The first argument to @code{other-buffer}, the exception, is yet
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5186 another function, @code{current-buffer}. That is not going to be
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5187 returned. The second argument is the symbol for true, @code{t}. that
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5188 tells @code{other-buffer} that it may show visible buffers (except in
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5189 this case, it will not show the current buffer, which makes sense).
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5190
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5191 @need 1250
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5192 The expression looks like this:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5193
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5194 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5195 (other-buffer (current-buffer) t)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5196 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5197
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5198 The second and third arguments to the @code{list} expression are
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5199 @code{(region-beginning)} and @code{(region-end)}. These two
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5200 functions specify the beginning and end of the text to be appended.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5201
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5202 @need 1250
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5203 Originally, the command used the letters @samp{B} and @samp{r}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5204 The whole @code{interactive} expression looked like this:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5205
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5206 @smallexample
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5207 (interactive "BAppend to buffer:@: \nr")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5208 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5209
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5210 @noindent
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5211 But when that was done, the default value of the buffer switched to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5212 was invisible. That was not wanted.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5213
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5214 (The prompt was separated from the second argument with a newline,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5215 @samp{\n}. It was followed by an @samp{r} that told Emacs to bind the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5216 two arguments that follow the symbol @code{buffer} in the function's
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5217 argument list (that is, @code{start} and @code{end}) to the values of
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5218 point and mark. That argument worked fine.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5219
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5220 @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
5221 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5222 @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
5223
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5224 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5225 in GNU Emacs 22 in /usr/local/src/emacs/lisp/simple.el
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5226
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5227 (defun append-to-buffer (buffer start end)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5228 "Append to specified buffer the text of the region.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5229 It is inserted into that buffer before its point.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5230
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5231 When calling from a program, give three arguments:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5232 BUFFER (or buffer name), START and END.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5233 START and END specify the portion of the current buffer to be copied."
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5234 (interactive
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5235 (list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t))
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5236 (region-beginning) (region-end)))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5237 (let ((oldbuf (current-buffer)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5238 (save-excursion
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5239 (let* ((append-to (get-buffer-create buffer))
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5240 (windows (get-buffer-window-list append-to t t))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5241 point)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5242 (set-buffer append-to)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5243 (setq point (point))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5244 (barf-if-buffer-read-only)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5245 (insert-buffer-substring oldbuf start end)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5246 (dolist (window windows)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5247 (when (= (window-point window) point)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5248 (set-window-point window (point))))))))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5249 @end ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5250
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5251 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
5252
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5253 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
5254 @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
5255 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
5256 @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
5257 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
5258
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5259 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
5260 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
5261 @code{let} expression in outline:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5262
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5263 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5264 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5265 (defun append-to-buffer (buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5266 "@var{documentation}@dots{}"
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5267 (interactive @dots{})
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5268 (let ((@var{variable} @var{value}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5269 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5270 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5271 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5272
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5273 The @code{let} expression has three elements:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5274
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5275 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5276 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5277 The symbol @code{let};
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5278
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5279 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5280 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
5281 @code{(@var{variable} @var{value})};
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5282
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5283 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5284 The body of the @code{let} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5285 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5286
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5287 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5288 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
5289
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5290 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5291 (oldbuf (current-buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5292 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5293
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5294 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5295 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
5296 @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
5297 @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
5298 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
5299 which you will copy.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5300
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5301 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
5302 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
5303 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
5304 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
5305 The line looks like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5308 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5309 (let ((oldbuf (current-buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5310 @dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5311 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5312 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5313
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5314 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5315 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
5316 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
5317 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
5318 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
5319
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5320 @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
5321 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5322 @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
5323
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5324 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
5325 consists of a @code{save-excursion} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5326
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5327 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
5328 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
5329 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
5330 @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
5331 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
5332 @code{append-to-buffer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5333
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5334 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5335 @cindex Indentation for formatting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5336 @cindex Formatting convention
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5337 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
5338 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
5339 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
5340 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
5341 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
5342 this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5345 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5346 (defun @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5347 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5348 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5349 (let@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5350 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5351 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5352 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5353 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5354
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5355 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5356 @noindent
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5357 This formatting convention makes it easy to see that the lines in
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5358 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
5359 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
5360 @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
5361 with the @code{let}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5362
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5363 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5364 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5365 (let ((oldbuf (current-buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5366 (save-excursion
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5367 @dots{}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5368 (set-buffer @dots{})
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5369 (insert-buffer-substring oldbuf start end)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5370 @dots{}))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5371 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5372 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5373
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5374 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5375 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
5376 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
5377
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5378 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5379 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5380 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5381 @var{first-expression-in-body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5382 @var{second-expression-in-body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5383 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5384 @var{last-expression-in-body})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5385 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5386 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5387
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5388 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5389 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5390 In this function, the body of the @code{save-excursion} contains only
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5391 one expression, the @code{let*} expression. You know about a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5392 @code{let} function. The @code{let*} function is different. It has a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5393 @samp{*} in its name. It enables Emacs to set each variable in its
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5394 varlist in sequence, one after another.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5395
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5396 Its critical feature is that variables later in the varlist can make
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5397 use of the values to which Emacs set variables earlier in the varlist.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5398 @xref{fwd-para let, , The @code{let*} expression}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5399
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5400 We will skip functions like @code{let*} and focus on two: the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5401 @code{set-buffer} function and the @code{insert-buffer-substring}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5402 function.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5403
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5404 @need 1250
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5405 In the old days, the @code{set-buffer} expression was simply
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5406
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5407 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5408 (set-buffer (get-buffer-create buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5409 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5410
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5411 @need 1250
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5412 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5413 but now it is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5414
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5415 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5416 (set-buffer append-to)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5417 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5418
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5419 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5420 @code{append-to} is bound to @code{(get-buffer-create buffer)} earlier
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5421 on in the @code{let*} expression. That extra binding would not be
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5422 necessary except for that @code{append-to} is used later in the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5423 varlist as an argument to @code{get-buffer-window-list}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5424
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5425 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5426 in GNU Emacs 22
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5427
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5428 (let ((oldbuf (current-buffer)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5429 (save-excursion
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5430 (let* ((append-to (get-buffer-create buffer))
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5431 (windows (get-buffer-window-list append-to t t))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5432 point)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5433 (set-buffer append-to)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5434 (setq point (point))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5435 (barf-if-buffer-read-only)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5436 (insert-buffer-substring oldbuf start end)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5437 (dolist (window windows)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5438 (when (= (window-point window) point)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5439 (set-window-point window (point))))))))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5440 @end ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5441
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5442 The @code{append-to-buffer} function definition inserts text from the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5443 buffer in which you are currently to a named buffer. It happens that
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5444 @code{insert-buffer-substring} copies text from another buffer to the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5445 current buffer, just the reverse---that is why the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5446 @code{append-to-buffer} definition starts out with a @code{let} that
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5447 binds the local symbol @code{oldbuf} to the value returned by
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5448 @code{current-buffer}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5449
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5450 @need 1250
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5451 The @code{insert-buffer-substring} expression looks like this:
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5452
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5453 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5454 (insert-buffer-substring oldbuf start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5455 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5456
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5457 @noindent
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5458 The @code{insert-buffer-substring} function copies a string
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5459 @emph{from} the buffer specified as its first argument and inserts the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5460 string into the present buffer. In this case, the argument to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5461 @code{insert-buffer-substring} is the value of the variable created
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5462 and bound by the @code{let}, namely the value of @code{oldbuf}, which
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5463 was the current buffer when you gave the @code{append-to-buffer}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5464 command.
41421
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 After @code{insert-buffer-substring} has done its work,
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5467 @code{save-excursion} will restore the action to the original buffer
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5468 and @code{append-to-buffer} will have done its job.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5469
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5470 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5471 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
5472
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5473 @smallexample
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 (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
5476 (save-excursion ; @r{Keep track of buffer.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5477 @var{change-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5478 @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
5479
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5480 @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
5481 @var{let-the-local-meaning-of-}@code{oldbuf}@var{-disappear-when-finished}
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5482 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5483 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5484
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5485 In summary, @code{append-to-buffer} works as follows: it saves the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5486 value of the current buffer in the variable called @code{oldbuf}. It
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5487 gets the new buffer (creating one if need be) and switches Emacs'
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5488 attention to it. Using the value of @code{oldbuf}, it inserts the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5489 region of text from the old buffer into the new buffer; and then using
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5490 @code{save-excursion}, it brings you back to your original buffer.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5491
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5492 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
5493 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
5494 @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
5495 buffer. Many function definitions use @code{let},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5496 @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
5497
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5498 @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
5499 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5500 @section Review
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5501
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5502 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
5503
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5504 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5505 @item describe-function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5506 @itemx describe-variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5507 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
5508 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
5509
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5510 @item find-tag
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5511 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
5512 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
5513 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
5514 @key{META} key).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5515
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5516 @item save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5517 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
5518 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
5519 the current buffer and return to it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5520
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5521 @item push-mark
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5522 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
5523 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
5524 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
5525
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5526 @item goto-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5527 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
5528 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
5529 a position, such as @code{(point-min)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5530
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5531 @item insert-buffer-substring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5532 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
5533 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
5534
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5535 @item mark-whole-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5536 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
5537
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5538 @item set-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5539 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
5540 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
5541 to work on a different buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5542
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5543 @item get-buffer-create
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5544 @itemx get-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5545 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
5546 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
5547 buffer does not exist.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5548 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5549
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5550 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5551 @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
5552 @section Exercises
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5553
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5554 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5555 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5556 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
5557 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
5558
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5559 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5560 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
5561 message telling you whether a buffer exists.
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5564 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
5565 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5566 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5567
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5568 @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
5569 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5570 @chapter A Few More Complex Functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5571
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5572 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
5573 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
5574 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
5575 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
5576 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
5577 @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
5578 to which the name refers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5579
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5580 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
5581 * copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
5582 * insert-buffer:: Read-only, and with @code{or}.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
5583 * beginning-of-buffer:: Shows @code{goto-char},
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
5584 @code{point-min}, and @code{push-mark}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5585 * Second Buffer Related Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5586 * optional Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5587 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5588
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5589 @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
5590 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5591 @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
5592 @findex copy-to-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5593
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5594 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
5595 understand @code{copy-to-buffer}. This function copies text into a
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5596 buffer, but instead of adding to the second buffer, it replaces all the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5597 previous text in the second buffer.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5598
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5599 @need 800
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5600 The body of @code{copy-to-buffer} looks like this,
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5601
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5602 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5603 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5604 @dots{}
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5605 (interactive "BCopy to buffer: \nr")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5606 (let ((oldbuf (current-buffer)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5607 (with-current-buffer (get-buffer-create buffer)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5608 (barf-if-buffer-read-only)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5609 (erase-buffer)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5610 (save-excursion
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5611 (insert-buffer-substring oldbuf start end)))))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5612 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5613 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5614
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5615 The @code{copy-to-buffer} function has a simpler @code{interactive}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5616 expression than @code{append-to-buffer}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5617
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5618 @need 800
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5619 The definition then says
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5620
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5621 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5622 (with-current-buffer (get-buffer-create buffer) @dots{}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5623 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5624
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5625 First, look at the earliest inner expression; that is evaluated first.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5626 That expression starts with @code{get-buffer-create buffer}. The
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5627 function tells the computer to use the buffer with the name specified
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5628 as the one to which you are copying, or if such a buffer does not
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5629 exist, to create it. Then, the @code{with-current-buffer} function
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5630 evaluates its body with that buffer temporarily current.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5631
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5632 (This demonstrates another way to shift the computer's attention but
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5633 not the user's. The @code{append-to-buffer} function showed how to do
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5634 the same with @code{save-excursion} and @code{set-buffer}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5635 @code{with-current-buffer} is a newer, and arguably easier,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5636 mechanism.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5637
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5638 The @code{barf-if-buffer-read-only} function sends you an error
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5639 message saying the buffer is read-only if you cannot modify it.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5640
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5641 The next line has the @code{erase-buffer} function as its sole
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5642 contents. That function erases the buffer.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5643
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5644 Finally, the last two lines contain the @code{save-excursion}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5645 expression with @code{insert-buffer-substring} as its body.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5646 The @code{insert-buffer-substring} expression copies the text from
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5647 the buffer you are in (and you have not seen the computer shift its
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5648 attention, so you don't know that that buffer is now called
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5649 @code{oldbuf}).
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5650
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
5651 Incidentally, this is what is meant by `replacement'. To replace text,
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5652 Emacs erases the previous text and then inserts new text.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5653
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5654 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5655 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
5656
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5657 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5658 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5659 (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer})
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5660 (@var{with-the-buffer-you-are-copying-to}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5661 (@var{but-do-not-erase-or-copy-to-a-read-only-buffer})
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5662 (erase-buffer)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5663 (save-excursion
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5664 @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
5665 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5666 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5667
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5668 @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
5669 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5670 @section The Definition of @code{insert-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5671 @findex insert-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5672
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5673 @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
5674 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
5675 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
5676 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
5677
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
5678 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
5679 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
5680
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
5681 (@xref{New insert-buffer, , New Body for @code{insert-buffer}}, to see
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5682 a discussion of the new body.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5683
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5684 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
5685 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
5686 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
5687
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5688 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5689 * insert-buffer code::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
5690 * insert-buffer interactive:: When you can read, but not write.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
5691 * insert-buffer body:: The body has an @code{or} and a @code{let}.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
5692 * if & or:: Using an @code{if} instead of an @code{or}.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
5693 * Insert or:: How the @code{or} expression works.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
5694 * Insert let:: Two @code{save-excursion} expressions.
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
5695 * New insert-buffer::
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5696 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5697
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5698 @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
5699 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5700 @unnumberedsubsec The Code for @code{insert-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5701 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5702
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5703 @need 800
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5704 Here is the earlier code:
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5705
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5706 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5707 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5708 (defun insert-buffer (buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5709 "Insert after point the contents of BUFFER.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5710 Puts mark after the inserted text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5711 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
5712 (interactive "*bInsert buffer:@: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5713 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5714 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5715 (or (bufferp buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5716 (setq buffer (get-buffer buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5717 (let (start end newmark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5718 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5719 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5720 (set-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5721 (setq start (point-min) end (point-max)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5722 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5723 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5724 (insert-buffer-substring buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5725 (setq newmark (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5726 (push-mark newmark)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5727 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5728 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5729
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5730 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5731 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
5732 outline of the function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5733
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5734 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5735 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5736 (defun insert-buffer (buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5737 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5738 (interactive "*bInsert buffer:@: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5739 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5740 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5741 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5742
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5743 @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
5744 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5745 @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
5746 @findex interactive, @r{example use of}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5747
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5748 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
5749 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
5750 buffer:@: }.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5751
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5752 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
5753 * Read-only buffer:: When a buffer cannot be modified.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
5754 * b for interactive:: An existing buffer or else its name.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5755 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5756
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5757 @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
5758 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5759 @unnumberedsubsubsec A Read-only Buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5760 @cindex Read-only buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5761 @cindex Asterisk for read-only buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5762 @findex * @r{for read-only buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5763
44899
ebddb2618c17 Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 43431
diff changeset
5764 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
5765 read-only buffer---a buffer that cannot be modified. If
ebddb2618c17 Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 43431
diff changeset
5766 @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
5767 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
5768 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
5769 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
5770 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
5771
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5772 @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
5773 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5774 @unnumberedsubsubsec @samp{b} in an Interactive Expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5775
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5776 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
5777 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
5778 @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
5779 @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
5780 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
5781 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
5782 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
5783 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
5784 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
5785 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
5786 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
5787
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5788 The new and simplified code generates a list for @code{interactive}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5789 It uses the @code{barf-if-buffer-read-only} and @code{read-buffer}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5790 functions with which we are already familiar and the @code{progn}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5791 special form with which we are not. (It will be described later.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
5792
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5793 @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
5794 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5795 @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
5796
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5797 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
5798 @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
5799 @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
5800 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
5801 @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
5802 into the current buffer.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5805 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
5806 function like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5807
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5808 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5809 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5810 (defun insert-buffer (buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5811 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5812 (interactive "*bInsert buffer:@: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5813 (or @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5814 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5815 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5816 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5817 (let (@var{varlist})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5818 @var{body-of-}@code{let}@dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5819 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5820 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5821
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5822 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
5823 @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
5824 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
5825
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5826 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
5827 @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
5828
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5829 @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
5830 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5831 @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
5832
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5833 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
5834 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
5835 then the buffer itself must be got.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5836
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5837 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
5838 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
5839 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
5840 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
5841
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5842 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5843 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
5844
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5845 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5846 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5847 (if (not (holding-on-to-guest))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5848 (find-and-take-arm-of-guest))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5849 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5850 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5851
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5852 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
5853 buffer itself, we want to get it.
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5856 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
5857 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
5858
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5859 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5860 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5861 (if (not (bufferp buffer)) ; @r{if-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5862 (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
5863 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5864 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5865
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5866 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5867 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
5868 @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
5869 @w{@code{(setq buffer (get-buffer buffer))}}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5870
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5871 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
5872 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
5873 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
5874 @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
5875 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
5876 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
5877 @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
5878 Argument}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5879
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5880 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5881 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
5882 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
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 (not (bufferp buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5886 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5887
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5888 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5889 @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
5890 and false if its argument is true. So if @code{(bufferp buffer)}
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
5891 returns true, the @code{not} expression returns false and vice-verse:
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5892 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
5893
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5894 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
5895 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
5896 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
5897 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
5898 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
5899 a buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5900
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5901 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
5902 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
5903 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
5904 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
5905 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
5906 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
5907 @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
5908 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
5909
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5910 @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
5911 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5912 @subsection The @code{or} in the Body
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5913
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5914 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
5915 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
5916 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
5917 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
5918 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
5919 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
5920
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5921 @findex or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5922 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
5923 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
5924 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
5925 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
5926 returning the first non-@code{nil} value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5927
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5928 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5929 The @code{or} expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5930
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5931 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5932 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5933 (or (bufferp buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5934 (setq buffer (get-buffer buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5935 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5936 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5939 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
5940 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
5941 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
5942 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
5943 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
5944 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
5945 @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
5946
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5947 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
5948 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
5949 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
5950 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
5951 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
5952 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
5953 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
5954
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5955 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
5956 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
5957 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
5958 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
5959 buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5960
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5961 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5962 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
5963 written like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5964
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5965 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5966 (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
5967 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5968
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
5969 @node Insert let, New insert-buffer, Insert or, insert-buffer
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5970 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5971 @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
5972
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5973 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
5974 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
5975 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
5976 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
5977 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
5978 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
5979 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
5980
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5981 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5982 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
5983 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
5984 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
5985
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5986 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5987 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5988 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5989 (set-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5990 (setq start (point-min) end (point-max)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5991 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5992 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5993
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5994 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5995 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
5996 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
5997 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
5998 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
5999 @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
6000 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
6001 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
6002 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
6003 fourth.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6004
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6005 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
6006 @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
6007 @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
6008 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
6009
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6010 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6011 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
6012
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6013 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6014 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6015 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6016 (@var{inner-}@code{save-excursion}@var{-expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6017 (@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
6018 (insert-buffer-substring buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6019 (setq newmark (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6020 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6021 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6022
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6023 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6024 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
6025 @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
6026 @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
6027 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
6028 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
6029 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
6030 recorded in the variable @code{newmark}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6031
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6032 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
6033 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
6034
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6035 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
6036 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
6037 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
6038 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
6039 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
6040 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
6041 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
6042 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
6043 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
6044 by the first @code{save-excursion}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6045
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6046 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6047 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
6048
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6049 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6050 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6051 (let (start end newmark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6052 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6053 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6054 (set-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6055 (setq start (point-min) end (point-max)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6056 (insert-buffer-substring buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6057 (setq newmark (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6058 (push-mark newmark))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6059 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6060 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6061
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6062 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
6063 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
6064 @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
6065 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
6066 find and use again and again.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6067
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
6068 @node New insert-buffer, , Insert let, insert-buffer
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6069 @comment node-name, next, previous, up
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6070 @subsection New Body for @code{insert-buffer}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6071 @findex insert-buffer, new version body
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6072 @findex new version body for insert-buffer
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6073
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6074 The body in the GNU Emacs 22 version is more confusing than the original.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6075
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6076 @need 1250
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6077 It consists of two expressions,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6078
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6079 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6080 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6081 (push-mark
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6082 (save-excursion
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6083 (insert-buffer-substring (get-buffer buffer))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6084 (point)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6085
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6086 nil
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6087 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6088 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6089
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6090 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6091 except, and this is what confuses novices, very important work is done
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6092 inside the @code{push-mark} expression.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6093
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6094 The @code{get-buffer} function returns a buffer with the name
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6095 provided. You will note that the function is @emph{not} called
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6096 @code{get-buffer-create}; it does not create a buffer if one does not
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6097 already exist. The buffer returned by @code{get-buffer}, an existing
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6098 buffer, is passed to @code{insert-buffer-substring}, which inserts the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6099 whole of the buffer (since you did not specify anything else).
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6100
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6101 The location into which the buffer is inserted is recorded by
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6102 @code{push-mark}. Then the function returns @code{nil}, the value of
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6103 its last command. Put another way, the @code{insert-buffer} function
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6104 exists only to produce a side effect, inserting another buffer, not to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6105 return any value.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6106
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6107 @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
6108 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6109 @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
6110 @findex beginning-of-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6111
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6112 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
6113 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
6114 Simplified @code{beginning-of-buffer} Definition}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6115 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
6116
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6117 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
6118 @code{beginning-of-buffer} moves the cursor to the beginning of the
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6119 buffer (in truth, the beginning of the accessible portion of the
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6120 buffer), leaving the mark at the previous position. However, when the
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6121 command is invoked with a number between one and ten, the function
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6122 considers that number to be a fraction of the length of the buffer,
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6123 measured in tenths, and Emacs moves the cursor that fraction of the
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6124 way from the beginning of the buffer. Thus, you can either call this
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6125 function with the key command @kbd{M-<}, which will move the cursor to
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6126 the beginning of the buffer, or with a key command such as @kbd{C-u 7
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6127 M-<} which will move the cursor to a point 70% of the way through the
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6128 buffer. If a number bigger than ten is used for the argument, it
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6129 moves to the end of the buffer.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6130
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6131 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
6132 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
6133
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6134 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6135 * Optional Arguments::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
6136 * beginning-of-buffer opt arg:: Example with optional argument.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6137 * beginning-of-buffer complete::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6138 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6139
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6140 @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
6141 @subsection Optional Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6142
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6143 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
6144 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
6145 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
6146 @samp{Wrong number of arguments}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6147
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6148 @cindex Optional arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6149 @cindex Keyword
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6150 @findex optional
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6151 However, optional arguments are a feature of Lisp: a particular
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6152 @dfn{keyword} is used to tell the Lisp interpreter that an argument is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6153 optional. The keyword is @code{&optional}. (The @samp{&} in front of
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6154 @samp{optional} is part of the keyword.) In a function definition, if
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6155 an argument follows the keyword @code{&optional}, no value need be
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6156 passed to that argument when the function is called.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6157
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6158 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6159 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
6160 therefore looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6161
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6162 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6163 (defun beginning-of-buffer (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6164 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6165
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6166 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6167 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
6168
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6169 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6170 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6171 (defun beginning-of-buffer (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6172 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6173 (interactive "P")
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6174 (or (@var{is-the-argument-a-cons-cell} arg)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6175 (and @var{are-both-transient-mark-mode-and-mark-active-true})
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6176 (push-mark))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6177 (let (@var{determine-size-and-set-it})
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6178 (goto-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6179 (@var{if-there-is-an-argument}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6180 @var{figure-out-where-to-go}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6181 @var{else-go-to}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6182 (point-min))))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6183 @var{do-nicety}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6184 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6185 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6186
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6187 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
6188 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
6189 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
6190 if-then-else expression that figures out where to put the cursor if
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6191 there is an argument that is not a cons cell.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6192
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6193 (Since I do not explain a cons cell for many more chapters, please
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6194 consider ignoring the function @code{consp}. @xref{List
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6195 Implementation, , How Lists are Implemented}, and @ref{Cons Cell Type,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6196 , Cons Cell and List Types, elisp, The GNU Emacs Lisp Reference
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6197 Manual}.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6198
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6199 The @code{"P"} in the @code{interactive} expression tells Emacs to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6200 pass a prefix argument, if there is one, to the function in raw form.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6201 A prefix argument is made by typing the @key{META} key followed by a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6202 number, or by typing @kbd{C-u} and then a number. (If you don't type
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6203 a number, @kbd{C-u} defaults to a cons cell with a 4. A lowercase
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6204 @code{"p"} in the @code{interactive} expression causes the function to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6205 convert a prefix arg to a number.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6206
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6207 The true-or-false-test of the @code{if} expression looks complex, but
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6208 it is not: it checks whether @code{arg} has a value that is not
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6209 @code{nil} and whether it is a cons cell. (That is what @code{consp}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6210 does; it checks whether its argument is a cons cell.) If @code{arg}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6211 has a value that is not @code{nil} (and is not a cons cell), which
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6212 will be the case if @code{beginning-of-buffer} is called with a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6213 numeric argument, then this true-or-false-test will return true and
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6214 the then-part of the @code{if} expression will be evaluated. On the
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6215 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
6216 argument, the value of @code{arg} will be @code{nil} and the else-part
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6217 of the @code{if} expression will be evaluated. The else-part is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6218 simply @code{point-min}, and when this is the outcome, the whole
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6219 @code{goto-char} expression is @code{(goto-char (point-min))}, which
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6220 is how we saw the @code{beginning-of-buffer} function in its
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6221 simplified form.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6222
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6223 @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
6224 @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
6225
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6226 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
6227 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
6228 @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
6229 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
6230 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6231
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6232 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6233 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6234 (if (> (buffer-size) 10000)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6235 ;; @r{Avoid overflow for large buffer sizes!}
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6236 (* (prefix-numeric-value arg)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6237 (/ size 10))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6238 (/
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6239 (+ 10
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6240 (*
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6241 size (prefix-numeric-value arg))) 10)))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6242 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6243 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6244
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6245 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6246 * Disentangle beginning-of-buffer::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6247 * Large buffer case::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6248 * Small buffer case::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6249 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6251 @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
6252 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6253 @unnumberedsubsubsec Disentangle @code{beginning-of-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6254 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6255
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6256 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
6257 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
6258 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
6259 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
6260
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6261 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6262 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6263 (if (@var{buffer-is-large}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6264 @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
6265 @var{else-use-alternate-calculation}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6266 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6267 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6268
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6269 The true-or-false-test of this inner @code{if} expression checks the
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
6270 size of the buffer. The reason for this is that the old version 18
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
6271 Emacs used numbers that are no bigger than eight million or so and in
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
6272 the computation that followed, the programmer feared that Emacs might
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
6273 try to use over-large numbers if the buffer were large. The term
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
6274 `overflow', mentioned in the comment, means numbers that are over
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
6275 large. More recent versions of Emacs use larger numbers, but this
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
6276 code has not been touched, if only because people now look at buffers
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
6277 that are far, far larger than ever before.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6278
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6279 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
6280
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6281 @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
6282 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6283 @unnumberedsubsubsec What happens in a large buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6284
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6285 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
6286 whether the size of the buffer is greater than 10,000 characters. To do
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6287 this, it uses the @code{>} function and the computation of @code{size}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6288 that comes from the let expression.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6289
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6290 In the old days, the function @code{buffer-size} was used. Not only
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6291 was that function called several times, it gave the size of the whole
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6292 buffer, not the accessible part. The computation makes much more
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6293 sense when it handles just the accessible part. (@xref{Narrowing &
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6294 Widening, , Narrowing and Widening}, for more information on focusing
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6295 attention to an `accessible' part.)
41421
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6298 The line looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6299
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6300 @smallexample
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6301 (if (> size 10000)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6302 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6303
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6304 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6305 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6306 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
6307 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
6308
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6309 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6310 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6311 (*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6312 (prefix-numeric-value arg)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6313 (/ size 10))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6314 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6315 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6316
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6317 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6318 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
6319 @code{*}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6320
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6321 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
6322 @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
6323 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
6324 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
6325 the arithmetic, a conversion is necessary, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6326 @code{prefix-numeric-value} does the job.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6327
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6328 @findex / @r{(division)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6329 @cindex Division
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6330 The second argument is @code{(/ size 10)}. This expression divides
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6331 the numeric value by ten --- the numeric value of the size of the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6332 accessible portion of the buffer. This produces a number that tells
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6333 how many characters make up one tenth of the buffer size. (In Lisp,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6334 @code{/} is used for division, just as @code{*} is used for
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6335 multiplication.)
41421
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6338 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
6339 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
6340
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6341 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6342 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6343 (* @var{numeric-value-of-prefix-arg}
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6344 @var{number-of-characters-in-one-tenth-of-the-accessible-buffer})
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6345 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6346 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6347
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6348 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6349 If, for example, the prefix argument is @samp{7}, the one-tenth value
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6350 will be multiplied by 7 to give a position 70% of the way through.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6351
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6352 @need 1200
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6353 The result of all this is that if the accessible portion of the buffer
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6354 is large, the @code{goto-char} expression reads like this:
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6355
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6356 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6357 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6358 (goto-char (* (prefix-numeric-value arg)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6359 (/ size 10)))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6360 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6361 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6362
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6363 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
6364
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6365 @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
6366 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6367 @unnumberedsubsubsec What happens in a small buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6368
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6369 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
6370 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
6371 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
6372 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
6373 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
6374
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6375 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6376 The code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6377
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6378 @c Keep this on one line.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6379 @smallexample
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6380 (/ (+ 10 (* size (prefix-numeric-value arg))) 10))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6381 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6382
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6383 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6384 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6385 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
6386 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
6387 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
6388 enclosing expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6389
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6390 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6391 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6392 (/
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6393 (+ 10
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6394 (*
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6395 size
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6396 (prefix-numeric-value arg)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6397 10))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6398 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6399 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6400
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6401 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6402 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6403 Looking at parentheses, we see that the innermost operation is
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6404 @code{(prefix-numeric-value arg)}, which converts the raw argument to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6405 a number. In the following expression, this number is multiplied by
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6406 the size of the accessible portion of the buffer:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6407
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6408 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6409 (* size (prefix-numeric-value arg))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6410 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6411
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6412 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6413 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
6414 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
6415 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
6416 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
6417 position in the buffer.
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 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
6420 the cursor is moved to that point.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6421
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6422 @need 1500
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6423 @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
6424 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6425 @subsection The Complete @code{beginning-of-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6426
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6427 @need 1000
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6428 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
6429 @sp 1
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6430
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6431 @c In GNU Emacs 22
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6432 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6433 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6434 (defun beginning-of-buffer (&optional arg)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6435 "Move point to the beginning of the buffer;
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6436 leave mark at previous position.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6437 With \\[universal-argument] prefix,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6438 do not set mark at previous position.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6439 With numeric arg N,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6440 put point N/10 of the way from the beginning.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6441
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6442 If the buffer is narrowed,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6443 this command uses the beginning and size
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6444 of the accessible part of the buffer.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6445 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6446
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6447 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6448 Don't use this command in Lisp programs!
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6449 \(goto-char (point-min)) is faster
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6450 and avoids clobbering the mark."
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6451 (interactive "P")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6452 (or (consp arg)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6453 (and transient-mark-mode mark-active)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6454 (push-mark))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6455 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6456 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6457 (let ((size (- (point-max) (point-min))))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6458 (goto-char (if (and arg (not (consp arg)))
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6459 (+ (point-min)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6460 (if (> size 10000)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6461 ;; Avoid overflow for large buffer sizes!
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6462 (* (prefix-numeric-value arg)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6463 (/ size 10))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6464 (/ (+ 10 (* size (prefix-numeric-value arg))) 10)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6465 (point-min))))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6466 (if arg (forward-line 1)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6467 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6468 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6469
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6470 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6471 From before GNU Emacs 22
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6472 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6473 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6474 (defun beginning-of-buffer (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6475 "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
6476 leave mark at previous position.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6477 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
6478 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
6479 @end group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6480 @group
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6481 Don't use this in Lisp programs!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6482 \(goto-char (point-min)) is faster
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6483 and does not set the mark."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6484 (interactive "P")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6485 (push-mark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6486 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6487 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6488 (goto-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6489 (if arg
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6490 (if (> (buffer-size) 10000)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6491 ;; @r{Avoid overflow for large buffer sizes!}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6492 (* (prefix-numeric-value arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6493 (/ (buffer-size) 10))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6494 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6495 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6496 (/ (+ 10 (* (buffer-size)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6497 (prefix-numeric-value arg)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6498 10))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6499 (point-min)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6500 (if arg (forward-line 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6501 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6502 @end smallexample
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6503 @end ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6504
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6505 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6506 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
6507 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
6508 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
6509 the function.
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6512 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
6513
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6514 @smallexample
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6515 \\[universal-argument]
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6516 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6517
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6518 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6519 A @samp{\\} is used before the first square bracket of this
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6520 expression. This @samp{\\} tells the Lisp interpreter to substitute
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6521 whatever key is currently bound to the @samp{[@dots{}]}. In the case
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6522 of @code{universal-argument}, that is usually @kbd{C-u}, but it might
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6523 be different. (@xref{Documentation Tips, , Tips for Documentation
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6524 Strings, elisp, The GNU Emacs Lisp Reference Manual}, for more
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6525 information.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6526
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6527 @need 1200
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6528 Finally, the last line of the @code{beginning-of-buffer} command says
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6529 to move point to the beginning of the next line if the command is
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6530 invoked with an argument:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6531
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6532 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6533 (if arg (forward-line 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6534 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6535
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6536 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6537 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
6538 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
6539 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
6540 tenths of the way through the buffer, which is a nicety that is,
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6541 perhaps, not necessary, but which, if it did not occur, would be sure
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6542 to draw complaints.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6543
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6544 On the other hand, it also means that if you specify the command with
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6545 a @kbd{C-u}, but without a number, that is to say, if the `raw prefix
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6546 argument' is simply a cons cell, then the command puts you at the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6547 beginning of the second line @dots{} I don't know whether this is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6548 intended or whether no one has dealt with the code to avoid this
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6549 happening.
41421
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 @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
6552 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6553 @section Review
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6554
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6555 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
6556
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6557 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6558 @item or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6559 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
6560 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
6561 @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
6562 of the arguments; return a true value if one @emph{or} any of the
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6563 others are true.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6564
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6565 @item and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6566 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
6567 @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
6568 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
6569 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
6570 true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6571
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6572 @item &optional
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6573 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
6574 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
6575 argument, if desired.
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 @item prefix-numeric-value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6578 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
6579 "P")} to a numeric value.
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 @item forward-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6582 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
6583 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
6584 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
6585 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
6586 supposed to move but couldn't.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6587
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6588 @item erase-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6589 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
6590
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6591 @item bufferp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6592 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
6593 @end table
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 @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
6596 @section @code{optional} Argument Exercise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6597
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6598 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
6599 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
6600 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
6601 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
6602 56 as a default value.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6603
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6604 @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
6605 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6606 @chapter Narrowing and Widening
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6607 @cindex Focusing attention (narrowing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6608 @cindex Narrowing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6609 @cindex Widening
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 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
6612 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
6613 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
6614 novices.
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 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
6617 * Narrowing advantages:: The advantages of narrowing
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
6618 * save-restriction:: The @code{save-restriction} special form.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
6619 * what-line:: The number of the line that point is on.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6620 * narrow Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6621 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6622
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6623 @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
6624 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6625 @unnumberedsec The Advantages of Narrowing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6626 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6627
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6628 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
6629 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
6630 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
6631 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
6632 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
6633 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
6634 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
6635 narrowing just to the region you want.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6636 (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
6637
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6638 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
6639 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
6640 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
6641 (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
6642 (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
6643 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
6644 @code{widen} command.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6645 (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
6646
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6647 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
6648 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
6649 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
6650 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
6651 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
6652 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
6653 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
6654 @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
6655 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
6656 situation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6657
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6658 @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
6659 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6660 @section The @code{save-restriction} Special Form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6661 @findex save-restriction
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 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
6664 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
6665 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
6666 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
6667 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
6668 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
6669 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
6670 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
6671 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
6672 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
6673 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
6674 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6675
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6676 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6677 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
6678
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6679 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6680 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6681 (save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6682 @var{body}@dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6683 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6684 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6685
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6686 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6687 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
6688 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
6689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6690 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
6691 @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
6692 @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
6693 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
6694 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
6695 @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
6696 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6697
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6698 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6699 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6700 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6701 (save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6702 @var{body}@dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6703 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6704 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6705
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6706 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
6707 @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
6708 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
6709
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6710 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6711 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6712
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6713 @smallexample
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 (save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6716 (widen)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6717 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6718 @var{body}@dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6719 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6720 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6721
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6722 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6723 Emacs 22
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6724 /usr/local/src/emacs/lisp/simple.el
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6725
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6726 (defun what-line ()
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6727 "Print the current buffer line number and narrowed line number of point."
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6728 (interactive)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6729 (let ((start (point-min))
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6730 (n (line-number-at-pos)))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6731 (if (= start 1)
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6732 (message "Line %d" n)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6733 (save-excursion
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6734 (save-restriction
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6735 (widen)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6736 (message "line %d (narrowed line %d)"
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6737 (+ n (line-number-at-pos start) -1) n))))))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6738
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6739 (defun line-number-at-pos (&optional pos)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6740 "Return (narrowed) buffer line number at position POS.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6741 If POS is nil, use current buffer location.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6742 Counting starts at (point-min), so the value refers
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6743 to the contents of the accessible portion of the buffer."
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6744 (let ((opoint (or pos (point))) start)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6745 (save-excursion
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6746 (goto-char (point-min))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6747 (setq start (point))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6748 (goto-char opoint)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6749 (forward-line 0)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6750 (1+ (count-lines start (point))))))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6751
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6752 (defun count-lines (start end)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6753 "Return number of lines between START and END.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6754 This is usually the number of newlines between them,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6755 but can be one more if START is not equal to END
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6756 and the greater of them is not at the start of a line."
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6757 (save-excursion
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6758 (save-restriction
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6759 (narrow-to-region start end)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6760 (goto-char (point-min))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6761 (if (eq selective-display t)
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6762 (save-match-data
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6763 (let ((done 0))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6764 (while (re-search-forward "[\n\C-m]" nil t 40)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6765 (setq done (+ 40 done)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6766 (while (re-search-forward "[\n\C-m]" nil t 1)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6767 (setq done (+ 1 done)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6768 (goto-char (point-max))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6769 (if (and (/= start end)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6770 (not (bolp)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6771 (1+ done)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6772 done)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6773 (- (buffer-size) (forward-line (buffer-size)))))))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6774 @end ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6775
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6776 @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
6777 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6778 @section @code{what-line}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6779 @findex what-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6780 @cindex Widening, example of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6781
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6782 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
6783 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
6784 @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
6785 original text of the function:
41421
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6788 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6789 (defun what-line ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6790 "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
6791 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6792 (save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6793 (widen)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6794 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6795 (beginning-of-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6796 (message "Line %d"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6797 (1+ (count-lines 1 (point)))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6798 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6799 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6800
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6801 (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
6802 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
6803 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
6804 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
6805 you might want to look at it after figuring out how this version
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6806 works. You will probably need to use @kbd{C-h f}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6807 (@code{describe-function}). The newer version uses a conditional to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6808 determine whether the buffer has been narrowed.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6809
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6810 (Also, it uses @code{line-number-at-pos}, which among other simple
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6811 expressions, such as @code{(goto-char (point-min))}, moves point to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6812 the beginning of the current line with @code{(forward-line 0)} rather
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6813 than @code{beginning-of-line}.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6814
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6815 The @code{what-line} function as shown here has a documentation line
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6816 and is interactive, as you would expect. The next two lines use the
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6817 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
6818
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6819 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
6820 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
6821 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
6822
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6823 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
6824 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
6825 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
6826 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
6827 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
6828 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
6829 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
6830 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
6831 @code{save-restriction} special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6832
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6833 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
6834 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
6835 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
6836 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
6837
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6838 (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
6839 @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
6840 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
6841 @code{save-excursion} outermost.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6842
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6843 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6844 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
6845 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
6846 echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6847
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6848 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6849 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6850 (message "Line %d"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6851 (1+ (count-lines 1 (point)))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6852 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6853 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6854
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6855 The @code{message} function prints a one-line message at the bottom of
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6856 the Emacs screen. The first argument is inside of quotation marks and
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6857 is printed as a string of characters. However, it may contain a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6858 @samp{%d} expression to print a following argument. @samp{%d} prints
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6859 the argument as a decimal, so the message will say something such as
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6860 @samp{Line 243}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6861
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6862 @need 1200
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6863 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
6864 last line of the function:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6867 (1+ (count-lines 1 (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6868 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6869
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6870 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6871 GNU Emacs 22
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6872
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6873 (defun count-lines (start end)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6874 "Return number of lines between START and END.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6875 This is usually the number of newlines between them,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6876 but can be one more if START is not equal to END
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6877 and the greater of them is not at the start of a line."
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6878 (save-excursion
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6879 (save-restriction
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6880 (narrow-to-region start end)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6881 (goto-char (point-min))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6882 (if (eq selective-display t)
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6883 (save-match-data
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6884 (let ((done 0))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6885 (while (re-search-forward "[\n\C-m]" nil t 40)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6886 (setq done (+ 40 done)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6887 (while (re-search-forward "[\n\C-m]" nil t 1)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6888 (setq done (+ 1 done)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6889 (goto-char (point-max))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6890 (if (and (/= start end)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6891 (not (bolp)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6892 (1+ done)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6893 done)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6894 (- (buffer-size) (forward-line (buffer-size)))))))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6895 @end ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6896
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6897 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6898 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
6899 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
6900 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
6901 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
6902 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
6903 current line.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6904
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6905 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
6906 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
6907 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
6908 the original narrowing, if any.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6909
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6910 @node narrow Exercise, , what-line, Narrowing & Widening
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6911 @section Exercise with Narrowing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6912
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6913 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
6914 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
6915 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
6916 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
6917 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
6918 @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
6919 @code{buffer-substring}.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6920
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
6921 @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
6922 (@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
6923 have to investigate yourself; or perhaps you will have to use
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6924 @code{buffer-substring-no-properties} or
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6925 @code{filter-buffer-substring} @dots{}, yet other functions. Text
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6926 properties are a feature otherwise not discussed here. @xref{Text
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6927 Properties, , Text Properties, elisp, The GNU Emacs Lisp Reference
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6928 Manual}.)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6929
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
6930 Additionally, do you really need @code{goto-char} or @code{point-min}?
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
6931 Or can you write the function without them?
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6932
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6933 @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
6934 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6935 @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
6936 @findex car, @r{introduced}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6937 @findex cdr, @r{introduced}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6938
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6939 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
6940 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
6941 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
6942
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6943 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
6944 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
6945 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
6946
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6947 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
6948 * Strange Names:: An historical aside: why the strange names?
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
6949 * car & cdr:: Functions for extracting part of a list.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
6950 * cons:: Constructing a list.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
6951 * nthcdr:: Calling @code{cdr} repeatedly.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6952 * nth::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
6953 * setcar:: Changing the first element of a list.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
6954 * setcdr:: Changing the rest of a list.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6955 * cons Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6956 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6957
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6958 @node 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
6959 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6960 @unnumberedsec Strange Names
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6961 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6962
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6963 The 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
6964 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
6965 @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
6966 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
6967 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
6968 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
6969 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
6970 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
6971 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
6972 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
6973 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
6974 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
6975 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
6976 introduction.
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 @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
6979 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6980 @section @code{car} and @code{cdr}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6981
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6982 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
6983 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
6984 @code{rose}.
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6987 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
6988 evaluating the following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6989
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6990 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6991 (car '(rose violet daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6992 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6993
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6994 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6995 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
6996 area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6997
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6998 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
6999 @code{first} and this is often suggested.
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 @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
7002 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
7003 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
7004 `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
7005
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7006 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
7007 @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
7008 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
7009 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
7010 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
7011 buttercup)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7012
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
7013 @need 800
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7014 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
7015
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7016 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7017 (cdr '(rose violet daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7018 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7019
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7020 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7021 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
7022 the echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7023
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7024 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
7025 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
7026 elements are.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7027
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7028 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
7029 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
7030 @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
7031
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7032 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
7033
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7034 (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
7035 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
7036 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
7037 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
7038 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
7039 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
7040 after you will be grateful to you.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7041
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7042 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
7043 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
7044 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
7045 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
7046 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
7047 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
7048 the usual way:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7049
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7050 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7051 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7052 (car '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7053
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7054 (cdr '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7055 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7056 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7057
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7058 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
7059 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
7060 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
7061 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
7062
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7063 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7064 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7065 (car '((lion tiger cheetah)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7066 (gazelle antelope zebra)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7067 (whale dolphin seal)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7068 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7069 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7070
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7071 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7072 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
7073 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
7074 @code{((gazelle antelope zebra) (whale dolphin seal))}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7075
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7076 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7077 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7078 (cdr '((lion tiger cheetah)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7079 (gazelle antelope zebra)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7080 (whale dolphin seal)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7081 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7082 @end smallexample
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 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
7085 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
7086 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
7087
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7088 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
7089 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
7090 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
7091 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
7092 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
7093 @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
7094 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
7095 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
7096 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
7097 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
7098 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
7099 Emacs Lisp Reference Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7101 @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
7102 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7103 @section @code{cons}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7104 @findex cons, @r{introduced}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7105
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7106 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
7107 @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
7108 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
7109
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7110 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7111 (cons 'pine '(fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7112 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7113
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7114 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7115 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7116 After evaluating this list, you will see
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7117
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7118 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7119 (pine fir oak maple)
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
45663
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
7123 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
7124 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
7125 list.
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
7126
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
7127 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
7128 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
7129 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
7130 existing list, but creates a new one.
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
7131
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
7132 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
7133
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7134 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7135 * Build a list::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
7136 * length:: How to find the length of a list.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7137 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7138
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7139 @node Build a list, length, cons, cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7140 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7141 @unnumberedsubsec Build a list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7142 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7143
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7144 @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
7145 @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
7146 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
7147 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
7148 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
7149 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
7150 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
7151 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
7152 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
7153 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
7154
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7155 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7156 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7157 (cons 'buttercup ())
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7158 @result{} (buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7159 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7160
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7161 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7162 (cons 'daisy '(buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7163 @result{} (daisy buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7164 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7165
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7166 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7167 (cons 'violet '(daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7168 @result{} (violet daisy buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7169 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7170
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7171 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7172 (cons 'rose '(violet daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7173 @result{} (rose violet daisy buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7174 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7175 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7178 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
7179 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
7180 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
7181 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
7182 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
7183 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
7184
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7185 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
7186 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
7187 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
7188 @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
7189
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7190 @node length, , Build a list, cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7191 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7192 @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
7193 @findex length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7194
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7195 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
7196 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
7197
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7198 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7199 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7200 (length '(buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7201 @result{} 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7202 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7203
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7204 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7205 (length '(daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7206 @result{} 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7207 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7210 (length (cons 'violet '(daisy buttercup)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7211 @result{} 3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7212 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7213 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7214
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7215 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7216 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
7217 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
7218 its argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7219
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7220 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7221 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
7222 empty list:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7223
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7224 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7225 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7226 (length ())
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7227 @result{} 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7228 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7229 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7230
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7231 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7232 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
7233
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7234 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
7235 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
7236 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
7237
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7238 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7239 (length )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7240 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7241
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7242 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7243 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7244 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
7245
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7246 @smallexample
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7247 Lisp error: (wrong-number-of-arguments length 0)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7248 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7249
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7250 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7251 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
7252 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
7253 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
7254 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
7255 @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
7256
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7257 The part of the error message that says @samp{length} is the name of
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7258 the function.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7259
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7260 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7261 @code{length} is still a subroutine, but you need C-h f to discover that.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7262
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7263 In an earlier version:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7264 This is written with a special notation, @samp{#<subr},
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7265 that indicates that the function @code{length} is one of the primitive
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7266 functions written in C rather than in Emacs Lisp. (@samp{subr} is an
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7267 abbreviation for `subroutine'.) @xref{What Is a Function, , What Is a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7268 Function?, elisp , The GNU Emacs Lisp Reference Manual}, for more
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7269 about subroutines.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7270 @end ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7271
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7272 @node nthcdr, nth, cons, car cdr & cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7273 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7274 @section @code{nthcdr}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7275 @findex nthcdr
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7276
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7277 The @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
7278 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
7279
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7280 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
7281 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
7282 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
7283 @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
7284 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
7285 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
7286 @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
7287 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
7288 @code{()} is shown as @code{nil}.
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 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7291 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
7292 the @samp{@result{}} shows what is returned.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7293
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7294 @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 (cdr '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7297 @result{}(fir oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7298 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7299
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7300 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7301 (cdr '(fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7302 @result{} (oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7303 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7304
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7305 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7306 (cdr '(oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7307 @result{}(maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7308 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7309
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7310 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7311 (cdr '(maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7312 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7313 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7314
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7315 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7316 (cdr 'nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7317 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7318 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7321 (cdr ())
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7322 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7323 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7324 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7325
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7326 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7327 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
7328 between, like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7329
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7330 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7331 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7332 (cdr (cdr '(pine fir oak maple)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7333 @result{} (oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7334 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7335 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7336
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7337 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7338 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
7339 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
7340 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
7341 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
7342 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
7343 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
7344 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
7345 first two elements.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7346
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7347 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
7348 @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
7349 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
7350 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
7351 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
7352
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7353 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7354 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7355 (nthcdr 2 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7356 @result{} (oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7357 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7358 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7359
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7360 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7361 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
7362 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
7363 and 5:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7364
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7365 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7366 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7367 ;; @r{Leave the list as it was.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7368 (nthcdr 0 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7369 @result{} (pine fir oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7370 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7371
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7372 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7373 ;; @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
7374 (nthcdr 1 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7375 @result{} (fir oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7376 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7377
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7378 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7379 ;; @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
7380 (nthcdr 3 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7381 @result{} (maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7382 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7385 ;; @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
7386 (nthcdr 4 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7387 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7388 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7389
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7390 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7391 ;; @r{Return a copy lacking all elements.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7392 (nthcdr 5 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7393 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7394 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7395 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7396
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7397 @node nth, setcar, nthcdr, car cdr & cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7398 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7399 @section @code{nth}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7400 @findex nth
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7401
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7402 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
7403 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
7404 @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
7405
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7406 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7407 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
7408 @code{nth} would be:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7409
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7410 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7411 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7412 (defun nth (n list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7413 "Returns the Nth element of LIST.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7414 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
7415 (car (nthcdr n list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7416 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7417 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7418
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7419 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7420 (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
7421 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
7422
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7423 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
7424 This can be very convenient.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7425
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7426 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
7427 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
7428 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
7429 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
7430 is `one-based'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7431
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7432 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7433 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7434
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7435 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7436 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7437 (nth 0 '("one" "two" "three"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7438 @result{} "one"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7439
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7440 (nth 1 '("one" "two" "three"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7441 @result{} "two"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7442 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7443 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7444
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7445 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
7446 @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
7447 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
7448 @code{setcdr} functions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7449
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7450 @node setcar, setcdr, nth, car cdr & cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7451 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7452 @section @code{setcar}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7453 @findex setcar
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 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
7456 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
7457 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
7458 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
7459 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
7460
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7461 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7462 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
7463 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
7464
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7465 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7466 (setq animals '(antelope giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7467 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7470 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
7471 this expression in the usual fashion, by positioning the cursor after
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7472 the expression and typing @kbd{C-x C-e}. (I'm doing this right here
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7473 as I write this. This is one of the advantages of having the
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
7474 interpreter built into the computing environment. Incidentally, when
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7475 there is nothing on the line after the final parentheses, such as a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7476 comment, point can be on the next line. Thus, if your cursor is in
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7477 the first column of the next line, you do not need to move it.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7478 Indeed, Emacs permits any amount of white space after the final
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7479 parenthesis.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7480
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7481 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7482 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
7483 the list @code{(antelope giraffe lion tiger)}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7484
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7485 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7486 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7487 animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7488 @result{} (antelope giraffe lion tiger)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7489 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7490 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7491
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7492 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7493 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
7494 @code{(antelope giraffe lion tiger)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7495
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7496 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
7497 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
7498 @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
7499 @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
7500 usual fashion:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7501
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7502 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7503 (setcar animals 'hippopotamus)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7504 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7505
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7506 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7507 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7508 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
7509 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
7510
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7511 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7512 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7513 animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7514 @result{} (hippopotamus giraffe lion tiger)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7515 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7516 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7517
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7518 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7519 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
7520 @code{hippopotamus}.
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 So we can see that @code{setcar} did not add a new element to the list
70909
02b9c43722d2 (setcar): replace an antelope rather than
David Kastrup <dak@gnu.org>
parents: 70725
diff changeset
7523 as @code{cons} would have; it replaced @code{antelope} with
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7524 @code{hippopotamus}; it @emph{changed} the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7525
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7526 @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
7527 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7528 @section @code{setcdr}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7529 @findex setcdr
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7530
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7531 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
7532 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
7533 a list rather than the first element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7534
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
7535 (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
7536 @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
7537 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
7538
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7539 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7540 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
7541 domesticated animals by evaluating the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7542
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7543 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7544 (setq domesticated-animals '(horse cow sheep goat))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7545 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7546
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7547 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7548 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7549 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
7550 @code{(horse cow sheep goat)}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7551
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7552 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7553 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7554 domesticated-animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7555 @result{} (horse cow sheep goat)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7556 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7557 @end smallexample
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 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
7561 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
7562 @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
7563
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7564 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7565 (setcdr domesticated-animals '(cat dog))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7566 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7567
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7568 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7569 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
7570 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
7571 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
7572 evaluating the variable @code{domesticated-animals}:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7575 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7576 domesticated-animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7577 @result{} (horse cat dog)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7578 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7579 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7580
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7581 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7582 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
7583 @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
7584 @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
7585
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7586 @node cons Exercise, , setcdr, car cdr & cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7587 @section Exercise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7588
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7589 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
7590 @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
7591 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
7592 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
7593
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7594 @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
7595 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7596 @chapter Cutting and Storing Text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7597 @cindex Cutting and storing text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7598 @cindex Storing and cutting text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7599 @cindex Killing text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7600 @cindex Clipping text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7601 @cindex Erasing text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7602 @cindex Deleting text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7603
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7604 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
7605 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
7606 `yank' command.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7607
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7608 (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
7609 @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
7610 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
7611 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
7612 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
7613 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
7614 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
7615
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7616 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
7617 * Storing Text:: Text is stored in a list.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
7618 * zap-to-char:: Cutting out text up to a character.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
7619 * kill-region:: Cutting text out of a region.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
7620 * copy-region-as-kill:: A definition for copying text.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
7621 * Digression into C:: Minor note on C programming language macros.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
7622 * defvar:: How to give a variable an initial value.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7623 * cons & search-fwd Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7624 * search Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7625 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7626
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7627 @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
7628 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7629 @unnumberedsec Storing Text in a List
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7630 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7631
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7632 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
7633 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
7634 look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7635
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7636 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7637 ("a piece of text" "previous piece")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7638 @end smallexample
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7641 @noindent
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7642 The function @code{cons} can be used to create a new list from a piece
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7643 of text (an `atom', to use the jargon) and an existing list, like
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7644 this:
41421
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7647 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7648 (cons "another piece"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7649 '("a piece of text" "previous piece"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7650 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7651 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7652
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7653 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7654 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7655 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
7656 the echo area:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7657
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7658 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7659 ("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
7660 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7661
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7662 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
7663 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
7664 @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
7665 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
7666 second element of the original list:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7667
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7668 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7669 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7670 (car (nthcdr 1 '("another piece"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7671 "a piece of text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7672 "previous piece")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7673 @result{} "a piece of text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7674 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7675 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7676
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7677 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
7678 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
7679 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
7680 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
7681 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
7682 than nothing at all.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7683
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7684 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
7685 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
7686 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
7687 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
7688 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
7689 climb the foothills.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7690
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7691 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
7692 retrieved. @xref{Yanking, , Yanking Text Back}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7693
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7694 @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
7695 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7696 @section @code{zap-to-char}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7697 @findex zap-to-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7698
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
7699 The @code{zap-to-char} function changed little between GNU Emacs
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7700 version 19 and GNU Emacs version 22. However, @code{zap-to-char}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7701 calls another function, @code{kill-region}, which enjoyed a major
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7702 rewrite.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7703
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7704 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
7705 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
7706
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7707 The @code{kill-region} function in Emacs 22 is easier to read than the
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7708 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
7709 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
7710
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7711 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
7712
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7713 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
7714 * Complete zap-to-char:: The complete implementation.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
7715 * zap-to-char interactive:: A three part interactive expression.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
7716 * zap-to-char body:: A short overview.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
7717 * search-forward:: How to search for a string.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
7718 * progn:: The @code{progn} special form.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
7719 * Summing up zap-to-char:: Using @code{point} and @code{search-forward}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7720 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7721
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7722 @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
7723 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7724 @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
7725 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7726
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
7727 The @code{zap-to-char} function removes the text in the region between
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
7728 the location of the cursor (i.e., of point) up to and including the
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
7729 next occurrence of a specified character. The text that
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
7730 @code{zap-to-char} removes is put in the kill ring; and it can be
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
7731 retrieved from the kill ring by typing @kbd{C-y} (@code{yank}). If
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
7732 the command is given an argument, it removes text through that number
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
7733 of occurrences. Thus, if the cursor were at the beginning of this
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
7734 sentence and the character were @samp{s}, @samp{Thus} would be
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
7735 removed. If the argument were two, @samp{Thus, if the curs} would be
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
7736 removed, up to and including the @samp{s} in @samp{cursor}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7737
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7738 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
7739 ``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
7740 any text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7741
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7742 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
7743 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
7744 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
7745 deletion command.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7746
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7747 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7748 @c GNU Emacs version 19
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7749 (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
7750 "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
7751 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
7752 (interactive "*p\ncZap to char: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7753 (kill-region (point)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7754 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7755 (search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7756 (char-to-string char) nil nil arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7757 (point))))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7758 @end ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7759
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7760 @need 1250
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7761 Here is the complete text of the version 22 implementation of the function:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7762
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7763 @c GNU Emacs 22
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7764 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7765 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7766 (defun zap-to-char (arg char)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7767 "Kill up to and including ARG'th occurrence of CHAR.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7768 Case is ignored if `case-fold-search' is non-nil in the current buffer.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7769 Goes backward if ARG is negative; error if CHAR not found."
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7770 (interactive "p\ncZap to char: ")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7771 (if (char-table-p translation-table-for-input)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7772 (setq char (or (aref translation-table-for-input char) char)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7773 (kill-region (point) (progn
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
7774 (search-forward (char-to-string char) nil nil arg)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
7775 (point))))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
7776 @end group
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
7777 @end smallexample
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
7778
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
7779 The documentation is thorough. You do need to know the jargon meaning
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
7780 of the word `kill'.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7781
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7782 @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
7783 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7784 @subsection The @code{interactive} Expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7785
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7786 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7787 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
7788 this:
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 @smallexample
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7791 (interactive "p\ncZap to char: ")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7792 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7793
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7794 The part within quotation marks, @code{"p\ncZap to char:@: "}, specifies
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7795 two different things. First, and most simply, is the @samp{p}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7796 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
7797 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
7798 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
7799 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
7800 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
7801 this argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7802
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7803 The second part of @code{"p\ncZap to char:@: "} is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7804 @samp{cZap to char:@: }. In this part, the lower case @samp{c}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7805 indicates that @code{interactive} expects a prompt and that the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7806 argument will be a character. The prompt follows the @samp{c} and is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7807 the string @samp{Zap to char:@: } (with a space after the colon to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7808 make it look good).
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7809
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7810 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
7811 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
7812
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7813 In a read-only buffer, the @code{zap-to-char} function copies the text
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7814 to the kill ring, but does not remove it. The echo area displays a
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
7815 message saying that the buffer is read-only. Also, the terminal may
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7816 beep or blink at you.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7817
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7818 @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
7819 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7820 @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
7821
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7822 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
7823 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
7824 position of the cursor up to and including the specified character.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7825
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7826 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
7827
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7828 @smallexample
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7829 (if (char-table-p translation-table-for-input)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7830 (setq char (or (aref translation-table-for-input char) char)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7831 (kill-region (point) (progn
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7832 (search-forward (char-to-string char) nil nil arg)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7833 (point)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7834 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7835
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7836 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7837 @code{char-table-p} is an hitherto unseen function. It determines
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7838 whether its argument is a character table. When it is, it sets the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7839 character passed to @code{zap-to-char} to one of them, if that
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7840 character exists, or to the character itself. (This becomes important
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7841 for certain characters in non-European languages. The @code{aref}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7842 function extracts an element from an array. It is an array-specific
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7843 function that is not described in this document. @xref{Arrays, ,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7844 Arrays, elisp, The GNU Emacs Lisp Reference Manual}.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7845
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7846 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7847 @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
7848
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7849 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
7850 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
7851 @code{point}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7852
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7853 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
7854 @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
7855 then at @code{progn}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7856
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7857 @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
7858 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7859 @subsection The @code{search-forward} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7860 @findex search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7861
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7862 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
7863 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
7864 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
7865 last character in the target string. (In @code{zap-to-char}, the
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7866 target string is just one character long. @code{zap-to-char} uses the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7867 function @code{char-to-string} to ensure that the computer treats that
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7868 character as a string.) If the search is backwards,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7869 @code{search-forward} leaves point just before the first character in
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7870 the target. Also, @code{search-forward} returns @code{t} for true.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7871 (Moving point is therefore a `side effect'.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7872
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7873 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7874 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
7875
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7876 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7877 (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
7878 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7879
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7880 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
7881
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7882 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7883 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7884 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
7885 string, such as @samp{"z"}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7886
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7887 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
7888 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
7889 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
7890 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
7891 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
7892 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
7893 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
7894 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
7895 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
7896 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
7897 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
7898 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
7899
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7900 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7901 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
7902 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
7903 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
7904
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7905 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7906 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
7907 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
7908 @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
7909 signal an error when the search fails.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7910
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7911 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7912 The 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
7913 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
7914 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
7915 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
7916 backwards.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7917 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7918
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7919 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7920 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
7921
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7922 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7923 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7924 (search-forward "@var{target-string}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7925 @var{limit-of-search}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7926 @var{what-to-do-if-search-fails}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7927 @var{repeat-count})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7928 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7929 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7930
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7931 We will look at @code{progn} next.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7932
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7933 @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
7934 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7935 @subsection The @code{progn} Special Form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7936 @findex progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7937
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7938 @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
7939 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
7940 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
7941 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
7942
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7943 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7944 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
7945
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7946 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7947 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7948 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7949 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7950 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7951 @end smallexample
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 @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
7954 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
7955 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
7956
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7957 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
7958 @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
7959 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
7960 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
7961 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
7962 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
7963
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7964 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
7965 @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
7966 this case will be the location to which it has been moved by
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7967 @code{search-forward}. (In the source, a line that tells the function
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7968 to go to the previous character, if it is going forward, was commented
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7969 out in 1999; I don't remember whether that feature or mis-feature was
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7970 ever a part of the distributed source.) The value of @code{point} is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7971 returned by the @code{progn} expression and is passed to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7972 @code{kill-region} as @code{kill-region}'s second argument.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7973
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7974 @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
7975 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7976 @subsection Summing up @code{zap-to-char}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7977
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7978 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
7979 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
7980
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7981 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
7982 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
7983 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
7984 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
7985 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
7986 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
7987 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
7988
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7989 The @code{progn} special form is necessary because the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7990 @code{kill-region} command takes two arguments; and it would fail if
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7991 @code{search-forward} and @code{point} expressions were written in
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7992 sequence as two additional arguments. The @code{progn} expression is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7993 a single argument to @code{kill-region} and returns the one value that
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7994 @code{kill-region} needs for its second argument.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7995
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
7996 @node kill-region, copy-region-as-kill, zap-to-char, Cutting & Storing Text
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7997 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7998 @section @code{kill-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7999 @findex kill-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8001 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
8002 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
8003 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
8004
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8005 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8006 GNU Emacs 22:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8007
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8008 (defun kill-region (beg end &optional yank-handler)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8009 "Kill (\"cut\") text between point and mark.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8010 This deletes the text from the buffer and saves it in the kill ring.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8011 The command \\[yank] can retrieve it from there.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8012 \(If you want to kill and then yank immediately, use \\[kill-ring-save].)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8013
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8014 If you want to append the killed region to the last killed text,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8015 use \\[append-next-kill] before \\[kill-region].
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8016
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8017 If the buffer is read-only, Emacs will beep and refrain from deleting
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8018 the text, but put the text in the kill ring anyway. This means that
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8019 you can use the killing commands to copy text from a read-only buffer.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8020
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8021 This is the primitive for programs to kill text (as opposed to deleting it).
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8022 Supply two arguments, character positions indicating the stretch of text
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8023 to be killed.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8024 Any command that calls this function is a \"kill command\".
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8025 If the previous command was also a kill command,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8026 the text killed this time appends to the text killed last time
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8027 to make one entry in the kill ring.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8028
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8029 In Lisp code, optional third arg YANK-HANDLER, if non-nil,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8030 specifies the yank-handler text property to be set on the killed
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8031 text. See `insert-for-yank'."
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8032 ;; Pass point first, then mark, because the order matters
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8033 ;; when calling kill-append.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8034 (interactive (list (point) (mark)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8035 (unless (and beg end)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8036 (error "The mark is not set now, so there is no region"))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8037 (condition-case nil
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8038 (let ((string (filter-buffer-substring beg end t)))
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8039 (when string ;STRING is nil if BEG = END
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8040 ;; Add that string to the kill ring, one way or another.
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8041 (if (eq last-command 'kill-region)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8042 (kill-append string (< end beg) yank-handler)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8043 (kill-new string nil yank-handler)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8044 (when (or string (eq last-command 'kill-region))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8045 (setq this-command 'kill-region))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8046 nil)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8047 ((buffer-read-only text-read-only)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8048 ;; The code above failed because the buffer, or some of the characters
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8049 ;; in the region, are read-only.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8050 ;; We should beep, in case the user just isn't aware of this.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8051 ;; However, there's no harm in putting
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8052 ;; the region's text in the kill ring, anyway.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8053 (copy-region-as-kill beg end)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8054 ;; Set this-command now, so it will be set even if we get an error.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8055 (setq this-command 'kill-region)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8056 ;; This should barf, if appropriate, and give us the correct error.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8057 (if kill-read-only-ok
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8058 (progn (message "Read only text copied to kill ring") nil)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8059 ;; Signal an error if the buffer is read-only.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8060 (barf-if-buffer-read-only)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8061 ;; If the buffer isn't read-only, the text is.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8062 (signal 'text-read-only (list (current-buffer)))))))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8063 @end ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8064
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8065 The Emacs 22 version of that function uses @code{condition-case} and
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8066 @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
8067 @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
8068
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8069 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
8070 @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
8071 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
8072 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
8073 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
8074
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8075 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
8076 * Complete kill-region:: The function definition.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
8077 * condition-case:: Dealing with a problem.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8078 * Lisp macro::
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8079 @end menu
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 @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
8082 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8083 @unnumberedsubsec The Complete @code{kill-region} Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8084 @end ifnottex
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8087 We will go through the @code{condition-case} code in a moment. First,
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8088 let us look at the definition of @code{kill-region}, with comments
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8089 added:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8090
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8091 @c GNU Emacs 22:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8092 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8093 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8094 (defun kill-region (beg end)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8095 "Kill (\"cut\") text between point and mark.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8096 This deletes the text from the buffer and saves it in the kill ring.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8097 The command \\[yank] can retrieve it from there. @dots{} "
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8098 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8099
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8100 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8101 ;; @bullet{} Since order matters, pass point first.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8102 (interactive (list (point) (mark)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8103 ;; @bullet{} And tell us if we cannot cut the text.
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8104 ;; `unless' is an `if' without a then-part.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8105 (unless (and beg end)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8106 (error "The mark is not set now, so there is no region"))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8107 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8108
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8109 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8110 ;; @bullet{} `condition-case' takes three arguments.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8111 ;; If the first argument is nil, as it is here,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8112 ;; information about the error signal is not
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8113 ;; stored for use by another function.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8114 (condition-case nil
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8115 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8116
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8117 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8118 ;; @bullet{} The second argument to `condition-case' tells the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8119 ;; Lisp interpreter what to do when all goes well.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8120 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8121
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8122 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8123 ;; It starts with a `let' function that extracts the string
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8124 ;; and tests whether it exists. If so (that is what the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8125 ;; `when' checks), it calls an `if' function that determines
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8126 ;; whether the previous command was another call to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8127 ;; `kill-region'; if it was, then the new text is appended to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8128 ;; the previous text; if not, then a different function,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8129 ;; `kill-new', is called.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8130 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8131
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8132 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8133 ;; The `kill-append' function concatenates the new string and
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8134 ;; the old. The `kill-new' function inserts text into a new
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8135 ;; item in the kill ring.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8136 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8137
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8138 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8139 ;; `when' is an `if' without an else-part. The second `when'
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8140 ;; again checks whether the current string exists; in
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8141 ;; addition, it checks whether the previous command was
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8142 ;; another call to `kill-region'. If one or the other
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8143 ;; condition is true, then it sets the current command to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8144 ;; be `kill-region'.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8145 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8146 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8147 (let ((string (filter-buffer-substring beg end t)))
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8148 (when string ;STRING is nil if BEG = END
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8149 ;; Add that string to the kill ring, one way or another.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8150 (if (eq last-command 'kill-region)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8151 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8152 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8153 ;; @minus{} `yank-handler' is an optional argument to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8154 ;; `kill-region' that tells the `kill-append' and
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8155 ;; `kill-new' functions how deal with properties
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8156 ;; added to the text, such as `bold' or `italics'.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8157 (kill-append string (< end beg) yank-handler)
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8158 (kill-new string nil yank-handler)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8159 (when (or string (eq last-command 'kill-region))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8160 (setq this-command 'kill-region))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8161 nil)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8162 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8163
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8164 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8165 ;; @bullet{} The third argument to `condition-case' tells the interpreter
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8166 ;; what to do with an error.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8167 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8168 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8169 ;; The third argument has a conditions part and a body part.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8170 ;; If the conditions are met (in this case,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8171 ;; if text or buffer are read-only)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8172 ;; then the body is executed.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8173 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8174 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8175 ;; The first part of the third argument is the following:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8176 ((buffer-read-only text-read-only) ;; the if-part
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
8177 ;; @dots{} the then-part
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8178 (copy-region-as-kill beg end)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8179 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8180 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8181 ;; Next, also as part of the then-part, set this-command, so
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8182 ;; it will be set in an error
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8183 (setq this-command 'kill-region)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8184 ;; Finally, in the then-part, send a message if you may copy
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8185 ;; the text to the kill ring without signally an error, but
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8186 ;; don't if you may not.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8187 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8188 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8189 (if kill-read-only-ok
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8190 (progn (message "Read only text copied to kill ring") nil)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8191 (barf-if-buffer-read-only)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8192 ;; If the buffer isn't read-only, the text is.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8193 (signal 'text-read-only (list (current-buffer)))))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8194 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8195 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8196
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8197 @ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8198 @c v 21
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8199 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8200 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8201 (defun kill-region (beg end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8202 "Kill between point and mark.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8203 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
8204 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8205 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8206
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8207 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8208 ;; 1. `condition-case' takes three arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8209 ;; 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
8210 ;; information about the error signal is not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8211 ;; stored for use by another function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8212 (condition-case nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8213 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8214
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8215 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8216 ;; 2. The second argument to `condition-case'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8217 ;; 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
8218 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8221 ;; 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
8222 ;; 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
8223 ;; 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
8224 (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
8225 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8226
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8227 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8228 ;; `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
8229 ;; 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
8230 ;; previous command.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8231 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8232 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8233 ;; `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
8234 ;; `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
8235 (when string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8236 (if (eq last-command 'kill-region)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8237 ;; if true, prepend string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8238 (kill-append string (< end beg))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8239 (kill-new string)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8240 (setq this-command 'kill-region))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8241 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8242
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8243 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8244 ;; 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
8245 ;; what to do with an error.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8246 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8247 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8248 ;; 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
8249 ;; If the conditions are met (in this case,
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8250 ;; if text or buffer are read-only)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8251 ;; then the body is executed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8252 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8253 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8254 ((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
8255 ;; then...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8256 (copy-region-as-kill beg end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8257 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8258 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8259 (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
8260 (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
8261 ;; 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
8262 (barf-if-buffer-read-only)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8263 ;; 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
8264 (signal 'text-read-only (list (current-buffer)))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8265 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8266 @end smallexample
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8267 @end ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8268
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8269 @node condition-case, Lisp macro, Complete kill-region, kill-region
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8270 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8271 @subsection @code{condition-case}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8272 @findex condition-case
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8273
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8274 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
8275 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
8276 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
8277 ``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
8278 shows you a message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8279
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8280 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
8281 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
8282 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
8283 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
8284 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
8285 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
8286 special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8287
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8288 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8289 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
8290
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8291 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8292 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8293 (condition-case
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8294 @var{var}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8295 @var{bodyform}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8296 @var{error-handler}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8297 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8298 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8299
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8300 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
8301 @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
8302 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
8303 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
8304
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8305 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
8306 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
8307 correctly.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8308
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8309 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
8310 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
8311 names.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8312
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8313 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
8314 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
8315 @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
8316 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
8317 part of the error handler is run.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8318
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8319 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
8320 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
8321
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8322 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
8323 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
8324 handler is run.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8325
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8326 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
8327 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
8328 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
8329 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
8330 discarded.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8331
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8332 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8333 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
8334 @code{condition-case} works like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8335
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8336 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8337 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8338 @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
8339 @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
8340 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8341 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8342
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8343 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8344 2006 Oct 24
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8345 In Emacs 22,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8346 copy-region-as-kill is short, 12 lines, and uses
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8347 filter-buffer-substring, which is longer, 39 lines
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8348 and has delete-and-extract-region in it.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8349 delete-and-extract-region is written in C.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8350
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8351 see Initializing a Variable with @code{defvar}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8352 this is line 8054
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8353 Initializing a Variable with @code{defvar} includes line 8350
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8354 @end ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8355
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8356 @node Lisp macro, , condition-case, kill-region
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8357 @comment node-name, next, previous, up
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8358 @subsection Lisp macro
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8359 @cindex Macro, lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8360 @cindex Lisp macro
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8361
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8362 The part of the @code{condition-case} expression that is evaluated in
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8363 the expectation that all goes well has a @code{when}. The code uses
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8364 @code{when} to determine whether the @code{string} variable points to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8365 text that exists.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8366
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8367 A @code{when} expression is simply a programmers' convenience. It is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8368 an @code{if} without the possibility of an else clause. In your mind,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8369 you can replace @code{when} with @code{if} and understand what goes
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8370 on. That is what the Lisp interpreter does.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8371
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8372 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
8373 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
8374 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
8375 expression which will in turn compute the value. In this case, the
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8376 `other expression' is an @code{if} expression.
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8377
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8378 The @code{kill-region} function definition also has an @code{unless}
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8379 macro; it is the converse of @code{when}. The @code{unless} macro is
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8380 an @code{if} without a then clause
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8381
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8382 For more about Lisp macros, see @ref{Macros, , Macros, elisp, The GNU
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8383 Emacs Lisp Reference Manual}. The C programming language also
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8384 provides macros. These are different, but also useful.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8385
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8386 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8387 We will briefly look at C macros in
45663
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
8388 @ref{Digression into C}.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8389 @end ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8390
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8391 @need 1200
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8392 Regarding the @code{when} macro, in the @code{condition-case}
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8393 expression, when the string has content, then another conditional
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8394 expression is executed. This is an @code{if} with both a then-part
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8395 and an else-part.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8396
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8397 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8398 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8399 (if (eq last-command 'kill-region)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8400 (kill-append string (< end beg) yank-handler)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8401 (kill-new string nil yank-handler))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8402 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8403 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8404
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8405 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
8406 @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
8407
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8408 @code{yank-handler} is an optional argument to @code{kill-region} that
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8409 tells the @code{kill-append} and @code{kill-new} functions how deal
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8410 with properties added to the text, such as `bold' or `italics'.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8411
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8412 @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
8413 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
8414 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
8415
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8416 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8417 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
8418 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
8419
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8420 @smallexample
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8421 (kill-append string (< end beg) yank-handler)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8422 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8423
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8424 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8425 concatenates a copy of the newly clipped text to the just previously
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8426 clipped text in the kill ring.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8427
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8428 @node copy-region-as-kill, Digression into C, kill-region, Cutting & Storing Text
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8429 @comment node-name, next, previous, up
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8430 @section @code{copy-region-as-kill}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8431 @findex copy-region-as-kill
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8432 @findex nthcdr
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8433
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8434 The @code{copy-region-as-kill} function copies a region of text from a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8435 buffer and (via either @code{kill-append} or @code{kill-new}) saves it
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8436 in the @code{kill-ring}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8437
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8438 If you call @code{copy-region-as-kill} immediately after a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8439 @code{kill-region} command, Emacs appends the newly copied text to the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8440 previously copied text. This means that if you yank back the text, you
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8441 get it all, from both this and the previous operation. On the other
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8442 hand, if some other command precedes the @code{copy-region-as-kill},
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8443 the function copies the text into a separate entry in the kill ring.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8444
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8445 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
8446 * Complete copy-region-as-kill:: The complete function definition.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
8447 * copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8448 @end menu
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8449
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8450 @node Complete copy-region-as-kill, copy-region-as-kill body, copy-region-as-kill, copy-region-as-kill
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8451 @ifnottex
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8452 @unnumberedsubsec The complete @code{copy-region-as-kill} function definition
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8453 @end ifnottex
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8454
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8455 @need 1200
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8456 Here is the complete text of the version 22 @code{copy-region-as-kill}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8457 function:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8458
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8459 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8460 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8461 (defun copy-region-as-kill (beg end)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8462 "Save the region as if killed, but don't kill it.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8463 In Transient Mark mode, deactivate the mark.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8464 If `interprogram-cut-function' is non-nil, also save the text for a window
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8465 system cut and paste."
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8466 (interactive "r")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8467 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8468 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8469 (if (eq last-command 'kill-region)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8470 (kill-append (filter-buffer-substring beg end) (< end beg))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8471 (kill-new (filter-buffer-substring beg end)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8472 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8473 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8474 (if transient-mark-mode
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8475 (setq deactivate-mark t))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8476 nil)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8477 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8478 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8479
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8480 @need 800
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8481 As usual, this function can be divided into its component parts:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8482
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8483 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8484 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8485 (defun copy-region-as-kill (@var{argument-list})
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8486 "@var{documentation}@dots{}"
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8487 (interactive "r")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8488 @var{body}@dots{})
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8489 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8490 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8491
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8492 The arguments are @code{beg} and @code{end} and the function is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8493 interactive with @code{"r"}, so the two arguments must refer to the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8494 beginning and end of the region. If you have been reading though this
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8495 document from the beginning, understanding these parts of a function is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8496 almost becoming routine.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8497
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8498 The documentation is somewhat confusing unless you remember that the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8499 word `kill' has a meaning different from usual. The `Transient Mark'
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8500 and @code{interprogram-cut-function} comments explain certain
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8501 side-effects.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8502
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8503 After you once set a mark, a buffer always contains a region. If you
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8504 wish, you can use Transient Mark mode to highlight the region
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8505 temporarily. (No one wants to highlight the region all the time, so
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8506 Transient Mark mode highlights it only at appropriate times. Many
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8507 people turn off Transient Mark mode, so the region is never
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8508 highlighted.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8509
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8510 Also, a windowing system allows you to copy, cut, and paste among
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8511 different programs. In the X windowing system, for example, the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8512 @code{interprogram-cut-function} function is @code{x-select-text},
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8513 which works with the windowing system's equivalent of the Emacs kill
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8514 ring.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8515
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8516 The body of the @code{copy-region-as-kill} function starts with an
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8517 @code{if} clause. What this clause does is distinguish between two
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8518 different situations: whether or not this command is executed
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8519 immediately after a previous @code{kill-region} command. In the first
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8520 case, the new region is appended to the previously copied text.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8521 Otherwise, it is inserted into the beginning of the kill ring as a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8522 separate piece of text from the previous piece.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8523
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8524 The last two lines of the function prevent the region from lighting up
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8525 if Transient Mark mode is turned on.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8526
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8527 The body of @code{copy-region-as-kill} merits discussion in detail.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8528
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8529 @node copy-region-as-kill body, , Complete copy-region-as-kill, copy-region-as-kill
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8530 @comment node-name, next, previous, up
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8531 @subsection The Body of @code{copy-region-as-kill}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8532
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8533 The @code{copy-region-as-kill} function works in much the same way as
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8534 the @code{kill-region} function. Both are written so that two or more
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8535 kills in a row combine their text into a single entry. If you yank
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8536 back the text from the kill ring, you get it all in one piece.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8537 Moreover, kills that kill forward from the current position of the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8538 cursor are added to the end of the previously copied text and commands
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8539 that copy text backwards add it to the beginning of the previously
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8540 copied text. This way, the words in the text stay in the proper
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8541 order.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8542
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8543 Like @code{kill-region}, the @code{copy-region-as-kill} function makes
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8544 use of the @code{last-command} variable that keeps track of the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8545 previous Emacs command.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8546
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8547 @menu
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8548 * last-command & this-command::
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8549 * kill-append function::
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8550 * kill-new function::
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8551 @end menu
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8552
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8553 @node last-command & this-command, kill-append function, copy-region-as-kill body, copy-region-as-kill body
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8554 @ifnottex
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8555 @unnumberedsubsubsec @code{last-command} and @code{this-command}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8556 @end ifnottex
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8557
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8558 Normally, whenever a function is executed, Emacs sets the value of
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8559 @code{this-command} to the function being executed (which in this case
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8560 would be @code{copy-region-as-kill}). At the same time, Emacs sets
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8561 the value of @code{last-command} to the previous value of
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8562 @code{this-command}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8563
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8564 In the first part of the body of the @code{copy-region-as-kill}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8565 function, an @code{if} expression determines whether the value of
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8566 @code{last-command} is @code{kill-region}. If so, the then-part of
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8567 the @code{if} expression is evaluated; it uses the @code{kill-append}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8568 function to concatenate the text copied at this call to the function
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8569 with the text already in the first element (the @sc{car}) of the kill
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8570 ring. On the other hand, if the value of @code{last-command} is not
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8571 @code{kill-region}, then the @code{copy-region-as-kill} function
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8572 attaches a new element to the kill ring using the @code{kill-new}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8573 function.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8574
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8575 @need 1250
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8576 The @code{if} expression reads as follows; it uses @code{eq}:
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8577
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8578 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8579 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8580 (if (eq last-command 'kill-region)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8581 ;; @r{then-part}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8582 (kill-append (filter-buffer-substring beg end) (< end beg))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8583 ;; @r{else-part}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8584 (kill-new (filter-buffer-substring beg end)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8585 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8586 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8587
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8588 @findex filter-buffer-substring
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8589 (The @code{filter-buffer-substring} function returns a filtered
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8590 substring of the buffer, if any. Optionally---the arguments are not
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8591 here, so neither is done---the function may delete the initial text or
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8592 return the text without its properties; this function is a replacement
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8593 for the older @code{buffer-substring} function, which came before text
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8594 properties were implemented.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8595
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8596 @findex eq @r{(example of use)}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8597 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8598 The @code{eq} function tests whether its first argument is the same Lisp
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8599 object as its second argument. The @code{eq} function is similar to the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8600 @code{equal} function in that it is used to test for equality, but
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8601 differs in that it determines whether two representations are actually
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8602 the same object inside the computer, but with different names.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8603 @code{equal} determines whether the structure and contents of two
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8604 expressions are the same.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8605
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8606 If the previous command was @code{kill-region}, then the Emacs Lisp
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8607 interpreter calls the @code{kill-append} function
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8608
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8609 @node kill-append function, kill-new function, last-command & this-command, copy-region-as-kill body
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8610 @unnumberedsubsubsec The @code{kill-append} function
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8611 @findex kill-append
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8612
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8613 @need 800
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8614 The @code{kill-append} function looks like this:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8615
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8616 @c in GNU Emacs 22
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8617 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8618 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8619 (defun kill-append (string before-p &optional yank-handler)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8620 "Append STRING to the end of the latest kill in the kill ring.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8621 If BEFORE-P is non-nil, prepend STRING to the kill.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8622 @dots{} "
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8623 (let* ((cur (car kill-ring)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8624 (kill-new (if before-p (concat string cur) (concat cur string))
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8625 (or (= (length cur) 0)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8626 (equal yank-handler
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8627 (get-text-property 0 'yank-handler cur)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8628 yank-handler)))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8629 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8630 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8631
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8632 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8633 was:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8634 (defun kill-append (string before-p)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8635 "Append STRING to the end of the latest kill in the kill ring.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8636 If BEFORE-P is non-nil, prepend STRING to the kill.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8637 If `interprogram-cut-function' is set, pass the resulting kill to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8638 it."
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8639 (kill-new (if before-p
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8640 (concat string (car kill-ring))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8641 (concat (car kill-ring) string))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8642 t))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8643 @end ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8644
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8645 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8646 The @code{kill-append} function is fairly straightforward. It uses
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8647 the @code{kill-new} function, which we will discuss in more detail in
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8648 a moment.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8649
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8650 (Also, the function provides an optional argument called
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8651 @code{yank-handler}; when invoked, this argument tells the function
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8652 how to deal with properties added to the text, such as `bold' or
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8653 `italics'.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8654
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8655 @c !!! bug in GNU Emacs 22 version of kill-append ?
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8656 It has a @code{let*} function to set the value of the first element of
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8657 the kill ring to @code{cur}. (I do not know why the function does not
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8658 use @code{let} instead; only one value is set in the expression.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8659 Perhaps this is a bug that produces no problems?)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8660
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8661 Consider the conditional that is one of the two arguments to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8662 @code{kill-new}. It uses @code{concat} to concatenate the new text to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8663 the @sc{car} of the kill ring. Whether it prepends or appends the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8664 text depends on the results of an @code{if} expression:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8665
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8666 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8667 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8668 (if before-p ; @r{if-part}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8669 (concat string cur) ; @r{then-part}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8670 (concat cur string)) ; @r{else-part}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8671 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8672 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8673
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8674 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8675 If the region being killed is before the region that was killed in the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8676 last command, then it should be prepended before the material that was
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8677 saved in the previous kill; and conversely, if the killed text follows
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8678 what was just killed, it should be appended after the previous text.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8679 The @code{if} expression depends on the predicate @code{before-p} to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8680 decide whether the newly saved text should be put before or after the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8681 previously saved text.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8682
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8683 The symbol @code{before-p} is the name of one of the arguments to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8684 @code{kill-append}. When the @code{kill-append} function is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8685 evaluated, it is bound to the value returned by evaluating the actual
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8686 argument. In this case, this is the expression @code{(< end beg)}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8687 This expression does not directly determine whether the killed text in
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8688 this command is located before or after the kill text of the last
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8689 command; what it does is determine whether the value of the variable
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8690 @code{end} is less than the value of the variable @code{beg}. If it
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8691 is, it means that the user is most likely heading towards the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8692 beginning of the buffer. Also, the result of evaluating the predicate
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8693 expression, @code{(< end beg)}, will be true and the text will be
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8694 prepended before the previous text. On the other hand, if the value of
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8695 the variable @code{end} is greater than the value of the variable
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8696 @code{beg}, the text will be appended after the previous text.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8697
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8698 @need 800
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8699 When the newly saved text will be prepended, then the string with the new
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8700 text will be concatenated before the old text:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8701
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8702 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8703 (concat string cur)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8704 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8705
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8706 @need 1200
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8707 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8708 But if the text will be appended, it will be concatenated
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8709 after the old text:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8710
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8711 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8712 (concat cur string))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8713 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8714
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8715 To understand how this works, we first need to review the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8716 @code{concat} function. The @code{concat} function links together or
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8717 unites two strings of text. The result is a string. For example:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8718
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8719 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8720 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8721 (concat "abc" "def")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8722 @result{} "abcdef"
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8723 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8724
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8725 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8726 (concat "new "
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8727 (car '("first element" "second element")))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8728 @result{} "new first element"
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8729
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8730 (concat (car
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8731 '("first element" "second element")) " modified")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8732 @result{} "first element modified"
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8733 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8734 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8735
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8736 We can now make sense of @code{kill-append}: it modifies the contents
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8737 of the kill ring. The kill ring is a list, each element of which is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8738 saved text. The @code{kill-append} function uses the @code{kill-new}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8739 function which in turn uses the @code{setcar} function.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8740
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8741 @node kill-new function, , kill-append function, copy-region-as-kill body
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8742 @unnumberedsubsubsec The @code{kill-new} function
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8743 @findex kill-new
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8744
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8745 @c in GNU Emacs 22, additional documentation to kill-new:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8746 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8747 Optional third arguments YANK-HANDLER controls how the STRING is later
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8748 inserted into a buffer; see `insert-for-yank' for details.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8749 When a yank handler is specified, STRING must be non-empty (the yank
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8750 handler, if non-nil, is stored as a `yank-handler' text property on STRING).
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8751
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8752 When the yank handler has a non-nil PARAM element, the original STRING
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8753 argument is not used by `insert-for-yank'. However, since Lisp code
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8754 may access and use elements from the kill ring directly, the STRING
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8755 argument should still be a \"useful\" string for such uses."
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8756 @end ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8757 @need 1200
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8758 The @code{kill-new} function looks like this:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8759
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8760 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8761 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8762 (defun kill-new (string &optional replace yank-handler)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8763 "Make STRING the latest kill in the kill ring.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8764 Set `kill-ring-yank-pointer' to point to it.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8765
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8766 If `interprogram-cut-function' is non-nil, apply it to STRING.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8767 Optional second argument REPLACE non-nil means that STRING will replace
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8768 the front of the kill ring, rather than being added to the list.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8769 @dots{}"
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8770 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8771 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8772 (if (> (length string) 0)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8773 (if yank-handler
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8774 (put-text-property 0 (length string)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8775 'yank-handler yank-handler string))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8776 (if yank-handler
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8777 (signal 'args-out-of-range
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8778 (list string "yank-handler specified for empty string"))))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8779 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8780 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8781 (if (fboundp 'menu-bar-update-yank-menu)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8782 (menu-bar-update-yank-menu string (and replace (car kill-ring))))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8783 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8784 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8785 (if (and replace kill-ring)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8786 (setcar kill-ring string)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8787 (push string kill-ring)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8788 (if (> (length kill-ring) kill-ring-max)
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8789 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8790 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8791 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8792 (setq kill-ring-yank-pointer kill-ring)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8793 (if interprogram-cut-function
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8794 (funcall interprogram-cut-function string (not replace))))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8795 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8796 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8797 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8798 was:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8799 (defun kill-new (string &optional replace)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8800 "Make STRING the latest kill in the kill ring.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8801 Set the kill-ring-yank pointer to point to it.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8802 If `interprogram-cut-function' is non-nil, apply it to STRING.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8803 Optional second argument REPLACE non-nil means that STRING will replace
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8804 the front of the kill ring, rather than being added to the list."
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8805 (and (fboundp 'menu-bar-update-yank-menu)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8806 (menu-bar-update-yank-menu string (and replace (car kill-ring))))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8807 (if (and replace kill-ring)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8808 (setcar kill-ring string)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8809 (setq kill-ring (cons string kill-ring))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8810 (if (> (length kill-ring) kill-ring-max)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8811 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8812 (setq kill-ring-yank-pointer kill-ring)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8813 (if interprogram-cut-function
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8814 (funcall interprogram-cut-function string (not replace))))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8815 @end ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8816
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8817 (Notice that the function is not interactive.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8818
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8819 As usual, we can look at this function in parts.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8820
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8821 The function definition has an optional @code{yank-handler} argument,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8822 which when invoked tells the function how to deal with properties
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8823 added to the text, such as `bold' or `italics'. We will skip that.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8824
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8825 @need 1200
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8826 The first line of the documentation makes sense:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8827
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8828 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8829 Make STRING the latest kill in the kill ring.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8830 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8831
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8832 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8833 Let's skip over the rest of the documentation for the moment.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8834
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
8835 @noindent
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8836 Also, let's skip over the initial @code{if} expression and those lines
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8837 of code involving @code{menu-bar-update-yank-menu}. We will explain
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8838 them below.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8839
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8840 @need 1200
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8841 The critical lines are these:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8842
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8843 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8844 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8845 (if (and replace kill-ring)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8846 ;; @r{then}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8847 (setcar kill-ring string)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8848 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8849 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8850 ;; @r{else}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8851 (push string kill-ring)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8852 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8853 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8854 (setq kill-ring (cons string kill-ring))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8855 (if (> (length kill-ring) kill-ring-max)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8856 ;; @r{avoid overly long kill ring}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8857 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8858 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8859 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8860 (setq kill-ring-yank-pointer kill-ring)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8861 (if interprogram-cut-function
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8862 (funcall interprogram-cut-function string (not replace))))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8863 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8864 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8865
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8866 The conditional test is @w{@code{(and replace kill-ring)}}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8867 This will be true when two conditions are met: the kill ring has
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8868 something in it, and the @code{replace} variable is true.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8869
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8870 @need 1250
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8871 When the @code{kill-append} function sets @code{replace} to be true
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8872 and when the kill ring has at least one item in it, the @code{setcar}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8873 expression is executed:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8874
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8875 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8876 (setcar kill-ring string)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8877 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8878
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8879 The @code{setcar} function actually changes the first element of the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8880 @code{kill-ring} list to the value of @code{string}. It replaces the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8881 first element.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8882
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8883 @need 1250
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8884 On the other hand, if the kill ring is empty, or replace is false, the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8885 else-part of the condition is executed:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8886
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8887 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8888 (push string kill-ring)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8889 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8890
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8891 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8892 @need 1250
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8893 @code{push} puts its first argument onto the second. It is similar to
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
8894 the older
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8895
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8896 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8897 (setq kill-ring (cons string kill-ring))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8898 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8899
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8900 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8901 @need 1250
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8902 or the newer
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8903
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8904 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8905 (add-to-list kill-ring string)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8906 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8907
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8908 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8909 When it is false, the expression first constructs a new version of the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8910 kill ring by prepending @code{string} to the existing kill ring as a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8911 new element (that is what the @code{push} does). Then it executes a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8912 second @code{if} clause. This second @code{if} clause keeps the kill
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8913 ring from growing too long.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8914
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8915 Let's look at these two expressions in order.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8916
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8917 The @code{push} line of the else-part sets the new value of the kill
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8918 ring to what results from adding the string being killed to the old
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8919 kill ring.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8920
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8921 We can see how this works with an example.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8922
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8923 @need 800
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8924 First,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8925
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8926 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8927 (setq example-list '("here is a clause" "another clause"))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8928 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8929
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8930 @need 1200
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8931 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8932 After evaluating this expression with @kbd{C-x C-e}, you can evaluate
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8933 @code{example-list} and see what it returns:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8934
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8935 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8936 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8937 example-list
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8938 @result{} ("here is a clause" "another clause")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8939 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8940 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8941
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8942 @need 1200
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8943 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8944 Now, we can add a new element on to this list by evaluating the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8945 following expression:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8946 @findex push, @r{example}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8947
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8948 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8949 (push "a third clause" example-list)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8950 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8951
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8952 @need 800
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8953 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8954 When we evaluate @code{example-list}, we find its value is:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8955
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8956 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8957 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8958 example-list
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8959 @result{} ("a third clause" "here is a clause" "another clause")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8960 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8961 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8962
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8963 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8964 Thus, the third clause is added to the list by @code{push}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8965
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8966 @need 1200
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8967 Now for the second part of the @code{if} clause. This expression
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8968 keeps the kill ring from growing too long. It looks like this:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8969
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8970 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8971 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8972 (if (> (length kill-ring) kill-ring-max)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8973 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8974 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8975 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8976
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8977 The code checks whether the length of the kill ring is greater than
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8978 the maximum permitted length. This is the value of
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8979 @code{kill-ring-max} (which is 60, by default). If the length of the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8980 kill ring is too long, then this code sets the last element of the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8981 kill ring to @code{nil}. It does this by using two functions,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8982 @code{nthcdr} and @code{setcdr}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8983
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8984 We looked at @code{setcdr} earlier (@pxref{setcdr, , @code{setcdr}}).
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8985 It sets the @sc{cdr} of a list, just as @code{setcar} sets the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8986 @sc{car} of a list. In this case, however, @code{setcdr} will not be
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8987 setting the @sc{cdr} of the whole kill ring; the @code{nthcdr}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8988 function is used to cause it to set the @sc{cdr} of the next to last
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8989 element of the kill ring---this means that since the @sc{cdr} of the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8990 next to last element is the last element of the kill ring, it will set
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8991 the last element of the kill ring.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8992
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8993 @findex nthcdr, @r{example}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8994 The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8995 list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8996 @dots{} It does this @var{N} times and returns the results.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8997 (@xref{nthcdr, , @code{nthcdr}}.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8998
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
8999 @findex setcdr, @r{example}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9000 Thus, if we had a four element list that was supposed to be three
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9001 elements long, we could set the @sc{cdr} of the next to last element
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
9002 to @code{nil}, and thereby shorten the list. (If you set the last
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9003 element to some other value than @code{nil}, which you could do, then
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9004 you would not have shortened the list. @xref{setcdr, ,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9005 @code{setcdr}}.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9006
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9007 You can see shortening by evaluating the following three expressions
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9008 in turn. First set the value of @code{trees} to @code{(maple oak pine
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9009 birch)}, then set the @sc{cdr} of its second @sc{cdr} to @code{nil}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9010 and then find the value of @code{trees}:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9011
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9012 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9013 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9014 (setq trees '(maple oak pine birch))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9015 @result{} (maple oak pine birch)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9016 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9017
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9018 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9019 (setcdr (nthcdr 2 trees) nil)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9020 @result{} nil
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9021
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9022 trees
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9023 @result{} (maple oak pine)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9024 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9025 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9026
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9027 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9028 (The value returned by the @code{setcdr} expression is @code{nil} since
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9029 that is what the @sc{cdr} is set to.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9030
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9031 To repeat, in @code{kill-new}, the @code{nthcdr} function takes the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9032 @sc{cdr} a number of times that is one less than the maximum permitted
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9033 size of the kill ring and @code{setcdr} sets the @sc{cdr} of that
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9034 element (which will be the rest of the elements in the kill ring) to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9035 @code{nil}. This prevents the kill ring from growing too long.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9036
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9037 @need 800
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9038 The next to last expression in the @code{kill-new} function is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9039
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9040 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9041 (setq kill-ring-yank-pointer kill-ring)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9042 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9043
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9044 The @code{kill-ring-yank-pointer} is a global variable that is set to be
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9045 the @code{kill-ring}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9046
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9047 Even though the @code{kill-ring-yank-pointer} is called a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9048 @samp{pointer}, it is a variable just like the kill ring. However, the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9049 name has been chosen to help humans understand how the variable is used.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9050
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9051 @need 1200
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9052 Now, to return to an early expression in the body of the function:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9053
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9054 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9055 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9056 (if (fboundp 'menu-bar-update-yank-menu)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9057 (menu-bar-update-yank-menu string (and replace (car kill-ring))))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9058 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9059 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9060
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9061 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9062 It starts with an @code{if} expression
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9063
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9064 In this case, the expression tests first to see whether
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9065 @code{menu-bar-update-yank-menu} exists as a function, and if so,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9066 calls it. The @code{fboundp} function returns true if the symbol it
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9067 is testing has a function definition that `is not void'. If the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9068 symbol's function definition were void, we would receive an error
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9069 message, as we did when we created errors intentionally (@pxref{Making
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9070 Errors, , Generate an Error Message}).
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9071
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9072 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9073 The then-part contains an expression whose first element is the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9074 function @code{and}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9075
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9076 @findex and
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9077 The @code{and} special form evaluates each of its arguments until one
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9078 of the arguments returns a value of @code{nil}, in which case the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9079 @code{and} expression returns @code{nil}; however, if none of the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9080 arguments returns a value of @code{nil}, the value resulting from
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9081 evaluating the last argument is returned. (Since such a value is not
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9082 @code{nil}, it is considered true in Emacs Lisp.) In other words, an
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9083 @code{and} expression returns a true value only if all its arguments
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9084 are true. (@xref{Second Buffer Related Review}.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9085
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9086 The expression determines whether the second argument to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9087 @code{menu-bar-update-yank-menu} is true or not.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9088 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9089 ;; If we're supposed to be extending an existing string, and that
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9090 ;; string really is at the front of the menu, then update it in place.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9091 @end ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9092
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9093 @code{menu-bar-update-yank-menu} is one of the functions that make it
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9094 possible to use the `Select and Paste' menu in the Edit item of a menu
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9095 bar; using a mouse, you can look at the various pieces of text you
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9096 have saved and select one piece to paste.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9097
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9098 The last expression in the @code{kill-new} function adds the newly
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9099 copied string to whatever facility exists for copying and pasting
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9100 among different programs running in a windowing system. In the X
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9101 Windowing system, for example, the @code{x-select-text} function takes
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9102 the string and stores it in memory operated by X. You can paste the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9103 string in another program, such as an Xterm.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9104
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9105 @need 1200
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9106 The expression looks like this:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9107
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9108 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9109 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9110 (if interprogram-cut-function
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9111 (funcall interprogram-cut-function string (not replace))))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9112 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9113 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9114
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9115 If an @code{interprogram-cut-function} exists, then Emacs executes
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9116 @code{funcall}, which in turn calls its first argument as a function
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9117 and passes the remaining arguments to it. (Incidentally, as far as I
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9118 can see, this @code{if} expression could be replaced by an @code{and}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9119 expression similar to the one in the first part of the function.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9120
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9121 We are not going to discuss windowing systems and other programs
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9122 further, but merely note that this is a mechanism that enables GNU
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9123 Emacs to work easily and well with other programs.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9124
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9125 This code for placing text in the kill ring, either concatenated with
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9126 an existing element or as a new element, leads us to the code for
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9127 bringing back text that has been cut out of the buffer---the yank
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9128 commands. However, before discussing the yank commands, it is better
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9129 to learn how lists are implemented in a computer. This will make
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
9130 clear such mysteries as the use of the term `pointer'. But before
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
9131 that, we will digress into C.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9132
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9133 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9134 @c is this true in Emacs 22? Does not seems to be
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9135
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9136 (If the @w{@code{(< end beg))}}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9137 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
9138 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
9139 @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
9140
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9141 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
9142 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
9143 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
9144 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
9145 order is correct.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9146
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9147 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
9148 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
9149 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
9150 @code{kill-ring-yank-pointer} variable to point to it.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9151 @end ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9152 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9153
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9154 @c Evidently, changed for Emacs 22. The zap-to-char command does not
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9155 @c use the delete-and-extract-region function
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9156
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9157 2006 Oct 26, the Digression into C is now OK but should come after
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9158 copy-region-as-kill and filter-buffer-substring
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9159
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9160 2006 Oct 24
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9161 In Emacs 22,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9162 copy-region-as-kill is short, 12 lines, and uses
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9163 filter-buffer-substring, which is longer, 39 lines
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9164 and has delete-and-extract-region in it.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9165 delete-and-extract-region is written in C.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9166
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9167 see Initializing a Variable with @code{defvar}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9168 @end ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9169
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9170 @node Digression into C, defvar, copy-region-as-kill, Cutting & Storing Text
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9171 @comment node-name, next, previous, up
45663
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
9172 @section Digression into C
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9173 @findex delete-and-extract-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9174 @cindex C, a digression into
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9175 @cindex Digression into C
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9176
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9177 The @code{copy-region-as-kill} function (@pxref{copy-region-as-kill, ,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9178 @code{copy-region-as-kill}}) uses the @code{filter-buffer-substring}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9179 function, which in turn uses the @code{delete-and-extract-region}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9180 function. It removes the contents of a region and you cannot get them
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9181 back.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9182
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9183 Unlike the other code discussed here, the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9184 @code{delete-and-extract-region} function is not written in Emacs
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9185 Lisp; it is written in C and is one of the primitives of the GNU Emacs
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9186 system. Since it is very simple, I will digress briefly from Lisp and
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9187 describe it here.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9188
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9189 @c GNU Emacs 22 in /usr/local/src/emacs/src/editfns.c
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9190 @c the DEFUN for buffer-substring-no-properties
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9191
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9192 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9193 Like many of the other Emacs primitives,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9194 @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
9195 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
9196 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9197
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9198 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9199 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9200 DEFUN ("buffer-substring-no-properties", Fbuffer_substring_no_properties,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9201 Sbuffer_substring_no_properties, 2, 2, 0,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9202 doc: /* Return the characters of part of the buffer,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9203 without the text properties.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9204 The two arguments START and END are character positions;
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9205 they can be in either order. */)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9206 (start, end)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9207 Lisp_Object start, end;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9208 @{
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9209 register int b, e;
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9210
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9211 validate_region (&start, &end);
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9212 b = XINT (start);
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9213 e = XINT (end);
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9214
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9215 return make_buffer_string (b, e, 0);
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9216 @}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9217 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9218 @end smallexample
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 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
9221 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
9222 @code{DEFUN} was chosen since the code serves the same purpose as
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9223 @code{defun} does in Lisp. (The @code{DEFUN} C macro is defined in
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9224 @file{emacs/src/lisp.h}.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9225
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9226 The word @code{DEFUN} is followed by seven parts inside of
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9227 parentheses:
41421
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 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9230 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9231 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
9232 @code{delete-and-extract-region}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9233
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9234 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9235 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
9236 @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
9237 @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
9238 instead.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9239
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9240 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9241 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
9242 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
9243 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
9244
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9245 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9246 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
9247 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
9248 arguments.
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9251 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
9252 @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
9253 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
9254 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
9255 (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
9256
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9257 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
9258 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
9259 @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
9260 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
9261 and provides a prompt.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9262
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9263 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9264 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
9265 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
9266 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
9267 return.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9268
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9269 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9270 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
9271 written like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9274 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9275 "Set point to POSITION, a number or marker.\n\
73607
95562bf680a2 Fix unbalanced quotes.
Juri Linkov <juri@jurta.org>
parents: 73597
diff changeset
9276 Beginning of buffer is position (point-min), end is (point-max)."
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9277 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9278 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9279 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9280
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9281 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9282 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
9283 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
9284 of the macro. For @code{delete-and-extract-region} the `body'
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9285 consists of the following four lines:
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9286
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9287 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9288 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9289 validate_region (&start, &end);
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9290 if (XINT (start) == XINT (end))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9291 return build_string ("");
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9292 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
9293 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9294 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9295
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9296 The @code{validate_region} function checks whether the values
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9297 passed as the beginning and end of the region are the proper type and
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9298 are within range. If the beginning and end positions are the same,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9299 then return and empty string.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9300
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9301 The @code{del_range_1} function actually deletes the text. It is a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9302 complex function we will not look into. It updates the buffer and
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9303 does other things. However, it is worth looking at the two arguments
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9304 passed to @code{del_range}. These are @w{@code{XINT (start)}} and
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9305 @w{@code{XINT (end)}}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9306
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9307 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
9308 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
9309 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
9310 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
9311 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
9312
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9313 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
9314 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
9315 lengths. Three of the available bits are used to specify the type of
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9316 information; the remaining bits are used as `content'.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9317
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9318 @samp{XINT} is a C macro that extracts the relevant number from the
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9319 longer collection of bits; the three other bits are discarded.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9320
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9321 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9322 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
9323
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9324 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9325 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
9326 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9329 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
9330 and the ending position, @code{end}.
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 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
9333 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
9334 all work.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9335
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9336 @node defvar, cons & search-fwd Review, Digression into C, Cutting & Storing Text
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9337 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9338 @section Initializing a Variable with @code{defvar}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9339 @findex defvar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9340 @cindex Initializing a variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9341 @cindex Variable initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9342
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9343 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9344 2006 Oct 24
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9345 In Emacs 22,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9346 copy-region-as-kill is short, 12 lines, and uses
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9347 filter-buffer-substring, which is longer, 39 lines
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9348 and has delete-and-extract-region in it.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9349 delete-and-extract-region is written in C.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9350
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9351 see Initializing a Variable with @code{defvar}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9352
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9353 @end ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9354
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9355 The @code{copy-region-as-kill} function is written in Emacs Lisp. Two
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9356 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
9357 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
9358 @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
9359 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
9360 form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9361
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9362 (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
9363 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
9364 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
9365
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9366 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
9367 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
9368 name comes from ``define variable''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9369
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9370 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
9371 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
9372 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
9373 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
9374 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
9375 documentation string.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9376
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9377 (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
9378 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
9379 (@xref{defcustom, , Setting Variables with @code{defcustom}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9380
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9381 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9382 * See variable current value::
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9383 * defvar and asterisk::
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9384 @end menu
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 @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
9387 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9388 @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
9389 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9390
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9391 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
9392 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
9393 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
9394 (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
9395 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
9396 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
9397 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
9398 @code{kill-ring}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9399
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9400 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9401 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9402 Documentation:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9403 List of killed text sequences.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9404 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
9405 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
9406 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9407 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9408 interact nicely with `interprogram-cut-function' and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9409 `interprogram-paste-function'. The functions `kill-new',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9410 `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
9411 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
9412 ring directly.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9413 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9414 @end smallexample
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9417 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
9418
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9419 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9420 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9421 (defvar kill-ring nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9422 "List of killed text sequences.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9423 @dots{}")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9424 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9425 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9426
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9427 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9428 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
9429 @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
9430 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
9431 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
9432 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
9433 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
9434 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
9435 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
9436 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
9437
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9438 @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
9439 @subsection @code{defvar} and an asterisk
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9440 @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
9441 @findex defvar @r{with an asterisk}
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 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
9444 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
9445 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
9446 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
9447 @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
9448 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
9449 using @code{defcustom}}.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9450
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9451 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
9452 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
9453 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
9454 string. For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9455
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9456 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9457 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9458 (defvar shell-command-default-error-buffer nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9459 "*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
9460 @dots{} ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9461 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9462 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9463
53099
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
9464 @findex set-variable
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
9465 @noindent
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
9466 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
9467 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
9468 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
9469 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
9470 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
9471 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
9472 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
9473 @xref{Emacs Initialization, , Your @file{.emacs} File}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9474
53099
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
9475 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
9476 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
9477 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
9478 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
9479 @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
9480 (@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
9481 The GNU Emacs Manual}.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9482
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9483 @need 1250
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9484 @node cons & search-fwd Review, search Exercises, defvar, Cutting & Storing Text
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9485 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9486 @section Review
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9487
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9488 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
9489
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9490 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9491 @item car
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9492 @itemx cdr
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9493 @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
9494 second and subsequent elements of a list.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9497 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9498
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9499 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9500 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9501 (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
9502 @result{} 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9503 (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
9504 @result{} (2 3 4 5 6 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9505 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9506 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9507
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9508 @item cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9509 @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
9510 second argument.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9513 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9514
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9515 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9516 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9517 (cons 1 '(2 3 4))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9518 @result{} (1 2 3 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9519 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9520 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9521
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
9522 @item funcall
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
9523 @code{funcall} evaluates its first argument as a function. It passes
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
9524 its remaining arguments to its first argument.
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
9525
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9526 @item nthcdr
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9527 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
9528 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9529 The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9530 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9531 $n^{th}$
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9532 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9533 @code{cdr}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9534 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9535 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
9536
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9537 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9538 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9539
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9540 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9541 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9542 (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
9543 @result{} (4 5 6 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9544 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9545 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9546
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9547 @item setcar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9548 @itemx setcdr
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9549 @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
9550 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
9551
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9552 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9553 For example:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9556 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9557 (setq triple '(1 2 3))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9558
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9559 (setcar triple '37)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9560
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9561 triple
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9562 @result{} (37 2 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9563
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9564 (setcdr triple '("foo" "bar"))
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 triple
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9567 @result{} (37 "foo" "bar")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9568 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9569 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9570
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9571 @item progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9572 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
9573 last.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9574
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9575 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9576 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9577
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9578 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9579 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9580 (progn 1 2 3 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9581 @result{} 4
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9582 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9583 @end smallexample
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 @item save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9586 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
9587 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
9588
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9589 @item search-forward
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
9590 Search for a string, and if the string is found, move point. With a
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
9591 regular expression, use the similar @code{re-search-forward}.
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
9592 (@xref{Regexp Search, , Regular Expression Searches}, for an
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
9593 explanation of regular expression patterns and searches.)
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
9594
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
9595 @need 1250
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
9596 @noindent
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
9597 @code{search-forward} and @code{re-search-forward} take four
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
9598 arguments:
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9599
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9600 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9601 @item
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
9602 The string or regular expression to search for.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9603
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9604 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9605 Optionally, the limit of the search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9606
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9607 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9608 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
9609 error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9610
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9611 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9612 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
9613 search goes backwards.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9614 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9615
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9616 @item kill-region
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
9617 @itemx delete-and-extract-region
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9618 @itemx copy-region-as-kill
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9619
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9620 @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
9621 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
9622 by yanking.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9623
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9624 @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
9625 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
9626 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
9627 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9628
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9629 @code{delete-and-extract-region} removes the text between point and
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9630 mark from the buffer and throws it away. You cannot get it back.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9631 (This is not an interactive command.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
9632
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9633 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9634 @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
9635 @section Searching Exercises
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9636
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9637 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9638 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9639 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
9640 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
9641 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
9642 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
9643 @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
9644 @code{test-search} instead.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9645
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9646 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9647 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
9648 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
9649 print an appropriate message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9650 @end itemize
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 @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
9653 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9654 @chapter How Lists are Implemented
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9655 @cindex Lists in a computer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9656
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9657 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
9658 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
9659 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
9660 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
9661 @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
9662 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
9663 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
9664 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
9665 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
9666 @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
9667
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9668 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
9669 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
9670
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9671 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9672 * Lists diagrammed::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
9673 * Symbols as Chest:: Exploring a powerful metaphor.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9674 * List Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9675 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9676
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9677 @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
9678 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9679 @unnumberedsec Lists diagrammed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9680 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9681
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9682 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
9683 @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
9684 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
9685 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
9686 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
9687 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
9688 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
9689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9690 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9691 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
9692
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9693 @c clear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9694 @c !!! cons-cell-diagram #1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9695 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9696 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9697 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9698 ___ ___ ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9699 |___|___|--> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9700 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9701 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9702 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9703 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9704 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9705 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9706 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9707 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9708 @tex
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
9709 @center @image{cons-1}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9710 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9711 % \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
9712 % \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
9713 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9714 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9715 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9716 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9717 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9718 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9719 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9720 @group
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 |___|___|--> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9723 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9724 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9725 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9726 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9727 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9728 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9729 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9730
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9731 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9732 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
9733 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
9734 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
9735 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
9736 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
9737 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
9738 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
9739 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
9740 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
9741
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9742 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9743 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
9744 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
9745 evaluation of the expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9746
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9747 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9748 (setq bouquet '(rose violet buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9749 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9750
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9751 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9752 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9753 creates a situation like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9754
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9755 @c cons-cell-diagram #2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9756 @ifnottex
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 bouquet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9760 |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9761 | ___ ___ ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9762 --> |___|___|--> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9763 | | |
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 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9766 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9767 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9768 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9769 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9770 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9771 @tex
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
9772 @center @image{cons-2}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9773 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9774 % \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
9775 % \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
9776 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9777 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9778 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9779 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9780 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9781 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9782 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9783 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9784 bouquet
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 | ___ ___ ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9787 --> |___|___|--> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9788 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9789 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9790 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9791 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9792 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9793 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9794 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9795
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9796 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9797 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
9798 pair of boxes.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9799
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9800 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9801 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
9802 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9803
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9804 @c cons-cell-diagram #2a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9805 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9806 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9807 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9808 bouquet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9809 |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9810 | -------------- --------------- ----------------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9811 | | car | cdr | | car | cdr | | car | cdr |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9812 -->| rose | o------->| violet | o------->| butter- | nil |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9813 | | | | | | | cup | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9814 -------------- --------------- ----------------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9815 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9816 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9817 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9818 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9819 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9820 @tex
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
9821 @center @image{cons-2a}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9822 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9823 % \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
9824 % \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
9825 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9826 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9827 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9828 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9829 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9830 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9831 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9832 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9833 bouquet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9834 |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9835 | -------------- --------------- ----------------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9836 | | car | cdr | | car | cdr | | car | cdr |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9837 -->| rose | o------->| violet | o------->| butter- | nil |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9838 | | | | | | | cup | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9839 -------------- --------------- ----------------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9840 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9841 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9842 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9843 @end ifclear
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 (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
9846 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
9847 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
9848 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
9849 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
9850 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
9851 @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
9852 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
9853 address-boxes for the list.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9854
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9855 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
9856 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
9857 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
9858 evaluation of the following expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9859
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9860 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9861 (setq flowers (cdr bouquet))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9862 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9863
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9864 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9865 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9866 produces this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9867
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9868 @c cons-cell-diagram #3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9869 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9870 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9871 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9872 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9873 bouquet flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9874 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9875 | ___ ___ | ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9876 --> | | | --> | | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9877 |___|___|----> |___|___|--> |___|___|--> nil
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 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9880 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9881 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9882 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9883 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9884 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9885 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9886 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9887 @tex
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
9888 @center @image{cons-3}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9889 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9890 % \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
9891 % \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
9892 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9893 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9894 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9895 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9896 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9897 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9898 @sp 1
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 bouquet flowers
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 |___|___|----> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9906 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9907 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9908 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9909 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9910 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9911 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9912 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9913 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9914
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9915 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9916 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
9917 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
9918 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
9919 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
9920
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9921 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
9922 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
9923 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
9924 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
9925 information about cons cells and dotted pairs.
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9928 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
9929 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
9930 the expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9931
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9932 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9933 (setq bouquet (cons 'lily bouquet))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9934 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9935
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9936 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9937 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9938 produces:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9939
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9940 @c cons-cell-diagram #4
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9941 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9942 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9943 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9944 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9945 bouquet flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9946 | |
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 --> | | | | | | --> | | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9949 |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9950 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9951 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9952 --> lily --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9953 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9954 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9955 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9956 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9957 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9958 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9959 @tex
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
9960 @center @image{cons-4}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9961 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9962 % \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
9963 % \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
9964 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9965 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9966 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9967 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9968 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9969 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9970 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9971 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9972 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9973 bouquet flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9974 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9975 | ___ ___ ___ ___ | ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9976 --> | | | | | | --> | | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9977 |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9978 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9979 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9980 --> lily --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9981 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9982 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9983 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9984 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9985 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9986
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9987 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9988 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9989 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
9990 @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
9991
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9992 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9993 (eq (cdr (cdr bouquet)) flowers)
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9997 which returns @code{t} for true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9998
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9999 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
10000 @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
10001 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
10002 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
10003
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10004 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
10005 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
10006 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
10007 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
10008 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
10009 brilliantly simple!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10010
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10011 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
10012 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
10013
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10014 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
10015 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
10016
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10017 @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
10018 @section Symbols as a Chest of Drawers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10019 @cindex Symbols as a Chest of Drawers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10020 @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
10021 @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
10022
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10023 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
10024 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
10025 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
10026 holding the value can be changed without affecting the contents of the
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
10027 drawer holding the function definition, and vice-verse.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10028
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10029 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
10030 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
10031 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
10032 where the buried treasure lies.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10033
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10034 (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
10035 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
10036 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
10037 @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
10038 Reference Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10039
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10040 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10041 Here is a fanciful representation:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10042
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10043 @c chest-of-drawers diagram
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10044 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10045 @sp 1
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10048 Chest of Drawers Contents of Drawers
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 __ o0O0o __
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10051 / \
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10052 ---------------------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10053 | directions to | [map to]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10054 | symbol name | bouquet
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 +---------------------+
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10057 | directions to |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10058 | symbol definition | [none]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10059 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10060 +---------------------+
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10061 | directions to | [map to]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10062 | variable value | (rose violet buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10063 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10064 +---------------------+
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10065 | directions to |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10066 | property list | [not described here]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10067 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10068 +---------------------+
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10069 |/ \|
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10070 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10071 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10072 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10073 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10074 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10075 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10076 @tex
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
10077 @center @image{drawers}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10078 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10079 % \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
10080 % \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
10081 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10082 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10083 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10084 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10085 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10086 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10087 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10088 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10089 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10090 Chest of Drawers Contents of Drawers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10091
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10092 __ o0O0o __
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10093 / \
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10094 ---------------------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10095 | directions to | [map to]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10096 | symbol name | bouquet
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 +---------------------+
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10099 | directions to |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10100 | symbol definition | [none]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10101 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10102 +---------------------+
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10103 | directions to | [map to]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10104 | variable value | (rose violet buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10105 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10106 +---------------------+
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10107 | directions to |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10108 | property list | [not described here]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10109 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10110 +---------------------+
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10111 |/ \|
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10112 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10113 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10114 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10115 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10116 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10117
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10118 @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
10119 @section Exercise
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 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
10122 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
10123 @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
10124 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
10125
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10126 @node Yanking, Loops & Recursion, List Implementation, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10127 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10128 @chapter Yanking Text Back
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10129 @findex yank
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10130 @cindex Text retrieval
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10131 @cindex Retrieving text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10132 @cindex Pasting text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10133
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10134 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
10135 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
10136 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
10137 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
10138 the original buffer).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10139
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10140 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
10141 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
10142 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
10143 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
10144 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
10145 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
10146 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
10147 `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
10148 that holds the text is a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10149 @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
10150 list is handled as a ring.)
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 @menu
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10153 * Kill Ring Overview::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
10154 * kill-ring-yank-pointer:: The kill ring is a list.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
10155 * yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10156 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10157
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10158 @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
10159 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10160 @section Kill Ring Overview
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10161 @cindex Kill ring overview
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10162
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10163 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
10164
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10165 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10166 ("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
10167 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10168
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10169 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
10170 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
10171 buffer where my cursor is located.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10172
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10173 The @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
10174 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
10175 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
10176
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10177 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
10178 @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
10179 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
10180 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
10181
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10182 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
10183 @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
10184 @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
10185
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10186 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10187 (insert (car kill-ring-yank-pointer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10188 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10189
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10190 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10191 (Well, no more. In GNU Emacs 22, the function has been replaced by
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10192 @code{insert-for-yank} which calls @code{insert-for-yank-1}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10193 repetitively for each @code{yank-handler} segment. In turn,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10194 @code{insert-for-yank-1} strips text properties from the inserted text
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10195 according to @code{yank-excluded-properties}. Otherwise, it is just
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10196 like @code{insert}. We will stick with plain @code{insert} since it
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10197 is easier to understand.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10198
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10199 To begin to understand how @code{yank} and @code{yank-pop} work, it is
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
10200 first necessary to look at the @code{kill-ring-yank-pointer} variable.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10201
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10202 @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
10203 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10204 @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
10205
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10206 @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
10207 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
10208 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
10209
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10210 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10211 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
10212
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10213 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10214 ("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
10215 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10216
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10217 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10218 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10219 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
10220 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
10221
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10222 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10223 ("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
10224 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10225
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10226 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
10227 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
10228 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
10229 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
10230 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
10231 text. Here is a diagram:
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 @c cons-cell-diagram #5
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10234 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10235 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10236 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10237 kill-ring kill-ring-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10238 | |
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 ---> | | | --> | | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10241 |___|___|----> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10242 | | |
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 | | --> "yet more text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10245 | |
73607
95562bf680a2 Fix unbalanced quotes.
Juri Linkov <juri@jurta.org>
parents: 73597
diff changeset
10246 | --> "a different piece of text"
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10247 |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10248 --> "some text"
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 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10252 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10253 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10254 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10255 @tex
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
10256 @center @image{cons-5}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10257 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10258 % \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
10259 % \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
10260 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10261 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10262 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10263 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10264 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10265 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10266 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10267 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10268 kill-ring kill-ring-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10269 | |
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 ---> | | | --> | | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10272 |___|___|----> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10273 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10274 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10275 | | --> "yet more text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10276 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10277 | --> "a different piece of text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10278 |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10279 --> "some text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10280 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10281 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10282 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10283 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10284 @end ifclear
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 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
10287 @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
10288 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
10289 @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
10290 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
10291 spoken of as pointing to a list.
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 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
10294 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
10295 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
10296 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
10297 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
10298 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
10299 inserted.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10300
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10301 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10302 In GNU Emacs 22, the @code{kill-new} function calls
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10303
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10304 @code{(setq kill-ring-yank-pointer kill-ring)}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10305
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10306 (defun rotate-yank-pointer (arg)
73619
e8162495e1ae * emacs-lisp-intro.texi (kill-ring-yank-pointer): Revert addition
Robert J. Chassell <bob@rattlesnake.com>
parents: 73610
diff changeset
10307 "Rotate the yanking point in the kill ring.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10308 With argument, rotate that many kills forward (or backward, if negative)."
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10309 (interactive "p")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10310 (current-kill arg))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10311
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10312 (defun current-kill (n &optional do-not-move)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10313 "Rotate the yanking point by N places, and then return that kill.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10314 If N is zero, `interprogram-paste-function' is set, and calling it
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10315 returns a string, then that string is added to the front of the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10316 kill ring and returned as the latest kill.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10317 If optional arg DO-NOT-MOVE is non-nil, then don't actually move the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10318 yanking point; just return the Nth kill forward."
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10319 (let ((interprogram-paste (and (= n 0)
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
10320 interprogram-paste-function
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
10321 (funcall interprogram-paste-function))))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10322 (if interprogram-paste
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
10323 (progn
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
10324 ;; Disable the interprogram cut function when we add the new
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
10325 ;; text to the kill ring, so Emacs doesn't try to own the
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
10326 ;; selection, with identical text.
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
10327 (let ((interprogram-cut-function nil))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
10328 (kill-new interprogram-paste))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
10329 interprogram-paste)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10330 (or kill-ring (error "Kill ring is empty"))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10331 (let ((ARGth-kill-element
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
10332 (nthcdr (mod (- n (length kill-ring-yank-pointer))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
10333 (length kill-ring))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
10334 kill-ring)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
10335 (or do-not-move
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
10336 (setq kill-ring-yank-pointer ARGth-kill-element))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
10337 (car ARGth-kill-element)))))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10338
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10339 @end ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10340
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10341 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10342 @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
10343 @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
10344
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10345 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10346 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10347 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
10348 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
10349 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
10350 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
10351 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
10352 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
10353
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10354 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10355 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
10356 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
10357 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10358
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10359 @node Loops & Recursion, Regexp Search, Yanking, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10360 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10361 @chapter Loops and Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10362 @cindex Loops and recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10363 @cindex Recursion and loops
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10364 @cindex Repetition (loops)
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 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
10367 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
10368 loop, and the other uses @dfn{recursion}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10369
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10370 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
10371 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
10372 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
10373 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
10374 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
10375 have on humans.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10376
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10377 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
10378 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
10379 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
10380 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
10381 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
10382 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
10383 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
10384 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
10385 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
10386 @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
10387 15 and 30 times their default value.}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10388
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10389 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
10390 * while:: Causing a stretch of code to repeat.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10391 * dolist dotimes::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
10392 * Recursion:: Causing a function to call itself.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10393 * Looping exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10394 @end menu
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 @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
10397 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10398 @section @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10399 @cindex Loops
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10400 @findex while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10401
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10402 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
10403 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
10404 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
10405 next, however, is different.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10406
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10407 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
10408 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
10409 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
10410 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
10411 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
10412 @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
10413 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
10414 body of the expression.
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 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10417 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
10418
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10419 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10420 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10421 (while @var{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10422 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10423 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10424 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10425
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10426 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
10427 * Looping with while:: Repeat so long as test returns true.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
10428 * Loop Example:: A @code{while} loop that uses a list.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
10429 * print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
10430 * Incrementing Loop:: A loop with an incrementing counter.
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
10431 * Incrementing Loop Details::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
10432 * Decrementing Loop:: A loop with a decrementing counter.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10433 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10434
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10435 @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
10436 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10437 @unnumberedsubsec Looping with @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10438 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10439
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10440 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
10441 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
10442 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
10443 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
10444 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
10445 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
10446 expression and `exits the loop'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10447
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10448 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
10449 @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
10450 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
10451 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
10452 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
10453 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
10454 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
10455 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
10456
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10457 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
10458 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
10459 @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
10460 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
10461 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
10462 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
10463 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
10464 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
10465 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
10466 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
10467 are repeatedly evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10468
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10469 @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
10470 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10471 @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
10472
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10473 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
10474 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
10475 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
10476 create a short example to illustrate it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10477
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10478 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
10479 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
10480 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
10481 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
10482 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
10483 @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
10484 @code{while} loop.
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10487 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
10488 evaluating the following @code{setq} expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10489
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10490 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10491 (setq empty-list ())
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10492 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10495 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
10496 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
10497 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
10498 echo area:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10499
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10500 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10501 empty-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10502 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10503
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10504 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
10505 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
10506 evaluating the following two expressions:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10507
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10508 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10509 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10510 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10511
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10512 animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10513 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10514 @end smallexample
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 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
10517 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
10518 written like this:
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 (while animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10523 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10524 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10525 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10526
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10527 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10528 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
10529 @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
10530 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
10531 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
10532 to be false.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10533
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10534 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
10535 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
10536 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
10537 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
10538 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
10539 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
10540 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
10541 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
10542
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10543 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
10544 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
10545 following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10546
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10547 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10548 (setq animals (cdr animals))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10549 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10550
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10551 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10552 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
10553 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
10554 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
10555 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
10556 @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
10557
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10558 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
10559 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
10560 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10561
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10562 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10563 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10564 (while @var{test-whether-list-is-empty}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10565 @var{body}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10566 @var{set-list-to-cdr-of-list})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10567 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10568 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10569
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10570 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
10571 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
10572 own.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10573
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10574 @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
10575 @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
10576 @findex print-elements-of-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10577
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10578 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
10579 loop with a list.
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 @cindex @file{*scratch*} buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10582 The function requires several lines for its output. If you are
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10583 reading this in a recent instance of GNU Emacs,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10584 @c GNU Emacs 21, GNU Emacs 22, or a later version,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10585 you can evaluate the following expression inside of Info, as usual.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10586
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10587 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
10588 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
10589 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
10590 earlier versions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10591
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10592 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
10593 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
10594 the end of the region and then copying the region using @kbd{M-w}
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10595 (@code{kill-ring-save}, which calls @code{copy-region-as-kill} and
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10596 then provides visual feedback). In the @file{*scratch*}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10597 buffer, you can yank the expressions back by typing @kbd{C-y}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10598 (@code{yank}).
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10599
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10600 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
10601 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
10602 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
10603 @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
10604 @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
10605 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
10606 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
10607 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
10608 each @samp{^J} stands for a `newline'.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10609
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10610 @need 1500
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10611 In a recent instance of GNU Emacs, you can evaluate these expressions
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10612 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
10613 results.
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10616 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10617 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10618
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10619 (defun print-elements-of-list (list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10620 "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
10621 (while list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10622 (print (car list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10623 (setq list (cdr list))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10624
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10625 (print-elements-of-list animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10626 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10627 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10628
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10629 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10630 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10631 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
10632 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
45663
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
10636 gazelle
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
10637
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10638 giraffe
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10639
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10640 lion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10641
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10642 tiger
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10643 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10644 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10645 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10646
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10647 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
10648 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
10649 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
10650 @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
10651 @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
10652
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
10653 @node Incrementing Loop, Incrementing Loop Details, print-elements-of-list, while
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10654 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10655 @subsection A Loop with an Incrementing Counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10656
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10657 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
10658 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
10659 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
10660 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
10661 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
10662 repeats itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10663
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
10664 @node Incrementing Loop Details, Decrementing Loop, Incrementing Loop, while
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
10665 @ifnottex
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
10666 @unnumberedsubsec Details of an Incrementing Loop
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
10667 @end ifnottex
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
10668
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
10669 The test for a loop with an incrementing counter can be an expression
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
10670 such as @code{(< count desired-number)} which returns @code{t} for
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
10671 true if the value of @code{count} is less than the
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
10672 @code{desired-number} of repetitions and @code{nil} for false if the
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
10673 value of @code{count} is equal to or is greater than the
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
10674 @code{desired-number}. The expression that increments the count can
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
10675 be a simple @code{setq} such as @code{(setq count (1+ count))}, where
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10676 @code{1+} is a built-in function in Emacs Lisp that adds 1 to its
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
10677 argument. (The expression @w{@code{(1+ count)}} has the same result
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
10678 as @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
10679
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10680 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10681 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
10682 counter looks like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10685 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10686 @var{set-count-to-initial-value}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10687 (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
10688 @var{body}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10689 (setq count (1+ count))) ; @r{incrementer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10690 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10691 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10692
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10693 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10694 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
10695 is set to 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10696
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10697 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
10698 * Incrementing Example:: Counting pebbles in a triangle.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
10699 * Inc Example parts:: The parts of the function definition.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
10700 * Inc Example altogether:: Putting the function definition together.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10701 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10702
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
10703 @node Incrementing Example, Inc Example parts, Incrementing Loop Details, Incrementing Loop Details
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10704 @unnumberedsubsubsec Example with incrementing counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10705
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10706 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
10707 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
10708 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
10709
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10710 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10711 @c pebble diagram
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10712 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10713 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10714 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10715 *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10716 * *
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 * * * *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10719 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10720 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10721 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10722 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10723 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10724 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10725 @bullet{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10726 @bullet{} @bullet{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10727 @bullet{} @bullet{} @bullet{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10728 @bullet{} @bullet{} @bullet{} @bullet{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10729 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10730 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10731 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10732 @sp 1
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10735 (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
10736 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
10737
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10738 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
10739 triangle with 7 rows?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10740
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10741 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
10742 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
10743 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
10744 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
10745 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
10746 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
10747 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
10748
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10749 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
10750 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
10751 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
10752 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
10753 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
10754 a more complex process once.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10755
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10756 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
10757 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
10758 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
10759 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
10760 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
10761
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10762 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
10763 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
10764 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
10765 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
10766 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
10767 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
10768 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
10769
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
10770 @node Inc Example parts, Inc Example altogether, Incrementing Example, Incrementing Loop Details
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10771 @unnumberedsubsubsec The parts of the function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10772
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10773 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
10774 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
10775 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
10776 the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10777
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10778 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
10779 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
10780 called @code{number-of-rows}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10781
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10782 Finally, we need a variable to use as a counter. We could call this
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10783 variable @code{counter}, but a better name is @code{row-number}. That
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10784 is because what the counter does in this function is count rows, and a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10785 program should be written to be as understandable as possible.
41421
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 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
10788 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
10789 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
10790 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
10791 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
10792 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
10793 more rows left to add.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10794
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10795 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
10796 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
10797 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
10798 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
10799 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
10800 statement will look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10801
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10802 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10803 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10804 (let ((total 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10805 (row-number 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10806 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10807 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10808 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10809
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10810 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
10811 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
10812 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
10813 @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
10814 (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
10815 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
10816 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
10817 equal to the number of rows.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10818
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10819 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10820 @findex <= @r{(less than or equal)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10821 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
10822 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
10823 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
10824 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
10825
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10826 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10827 (<= row-number number-of-rows)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10828 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10829
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10830 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
10831 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
10832 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
10833 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
10834 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
10835 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
10836 would be replaced by the appropriate expression.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10837
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10838 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10839 (setq total (+ total row-number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10840 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10841
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10842 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10843 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
10844 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
10845
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10846 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
10847 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
10848 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
10849 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
10850 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
10851 @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
10852 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
10853 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
10854 repetition of the loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10855
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10856 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10857 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
10858 @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
10859
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10860 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10861 (setq row-number (1+ row-number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10862 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10863
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
10864 @node Inc Example altogether, , Inc Example parts, Incrementing Loop Details
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10865 @unnumberedsubsubsec Putting the function definition together
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10866
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10867 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
10868 put them together.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10869
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10870 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10871 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
10872
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10873 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10874 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10875 (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
10876 (setq total (+ total row-number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10877 (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
10878 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10879 @end smallexample
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 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
10882 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
10883 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
10884
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10885 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
10886 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
10887 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
10888 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
10889 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
10890
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10891 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
10892 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
10893 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
10894 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
10895 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
10896 of the @code{let}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10897
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10898 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10899 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
10900
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10901 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10902 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10903 (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
10904 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10905 (let (@var{varlist})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10906 (while (@var{true-or-false-test})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10907 @var{body-of-while}@dots{} )
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
10908 @dots{} )) ; @r{Need final expression here.}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10909 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10910 @end smallexample
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 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
10913 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
10914 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
10915 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
10916 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
10917 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
10918 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
10919 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
10920 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
10921 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
10922
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10923 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
10924 @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
10925 @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
10926 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
10927 the last element:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10930 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10931 (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
10932 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10933 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10934
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10935 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10936 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
10937 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10938
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10939 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10940 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10941 (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
10942 ; @r{ incrementing counter.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10943 "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
10944 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
10945 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
10946 The argument is NUMBER-OF-ROWS."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10947 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10948 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10949 (let ((total 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10950 (row-number 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10951 (while (<= row-number number-of-rows)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10952 (setq total (+ total row-number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10953 (setq row-number (1+ row-number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10954 total))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10955 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10956 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10957
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10958 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10959 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
10960 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
10961
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10962 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10963 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10964 (triangle 4)
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 (triangle 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10967 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10968 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10969
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10970 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10971 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
10972 numbers is 28.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10973
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
10974 @node Decrementing Loop, , Incrementing Loop Details, while
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10975 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10976 @subsection Loop with a Decrementing Counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10977
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10978 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
10979 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
10980 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
10981 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
10982 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
10983 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
10984 repeatedly.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10985
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10986 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
10987 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
10988 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
10989 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
10990 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
10991 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
10992 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
10993
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10994 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10995 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
10996
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10997 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10998 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10999 (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
11000 @var{body}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11001 (setq counter (1- counter))) ; @r{decrementer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11002 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11003 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11004
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11005 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
11006 * Decrementing Example:: More pebbles on the beach.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
11007 * Dec Example parts:: The parts of the function definition.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
11008 * Dec Example altogether:: Putting the function definition together.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11009 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11010
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11011 @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
11012 @unnumberedsubsubsec Example with decrementing counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11013
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11014 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
11015 @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
11016
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11017 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
11018 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
11019 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
11020 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
11021 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
11022
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11023 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
11024 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
11025 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
11026 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
11027 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
11028 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
11029 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
11030 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
11031
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11032 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
11033 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
11034 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
11035 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
11036 the row.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11037
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11038 @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
11039 @unnumberedsubsubsec The parts of the function definition
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 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
11042 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
11043 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
11044 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
11045 @code{total}, respectively.
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 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
11048 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
11049 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
11050 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
11051 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
11052 the longest row.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11053
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11054 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11055 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
11056 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11057
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11058 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11059 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11060 (let ((total 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11061 (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
11062 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11063 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11064 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11065
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11066 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
11067 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
11068 evaluating the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11069
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11070 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11071 (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
11072 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11073
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11074 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11075 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
11076 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
11077 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
11078 added to the total.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11079
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11080 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
11081 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
11082 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
11083 done with the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11084
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11085 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11086 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11087 (setq number-of-pebbles-in-row
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11088 (1- number-of-pebbles-in-row))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11089 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11090 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11091
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11092 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
11093 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
11094 the @code{while} loop is simply:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11095
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11096 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11097 (while (> number-of-pebbles-in-row 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11098 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11099
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11100 @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
11101 @unnumberedsubsubsec Putting the function definition together
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11102
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11103 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
11104 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
11105 variables is unneeded!
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11108 The function definition looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11109
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11110 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11111 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11112 ;;; @r{First subtractive version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11113 (defun triangle (number-of-rows)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11114 "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
11115 (let ((total 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11116 (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
11117 (while (> number-of-pebbles-in-row 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11118 (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
11119 (setq number-of-pebbles-in-row
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11120 (1- number-of-pebbles-in-row)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11121 total))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11122 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11123 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11124
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11125 As written, this function works.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11126
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11127 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
11128
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11129 @cindex Argument as local variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11130 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
11131 @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
11132 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
11133 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
11134 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
11135 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
11136 @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
11137 @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
11138
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11139 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11140 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
11141
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11142 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11143 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11144 (defun triangle (number) ; @r{Second version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11145 "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
11146 (let ((total 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11147 (while (> number 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11148 (setq total (+ total number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11149 (setq number (1- number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11150 total))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11151 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11152 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11153
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11154 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
11155
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11156 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11157 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11158 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
11159 correct number of times.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11160
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11161 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11162 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
11163 after being repeatedly evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11164
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 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
11167 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
11168 number of times.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11169 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11170
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11171 @node dolist dotimes, Recursion, while, Loops & Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11172 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11173 @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
11174
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11175 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
11176 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
11177 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
11178 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
11179
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11180 @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
11181 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
11182 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
11183 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
11184
44899
ebddb2618c17 Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 43431
diff changeset
11185 @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
11186
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11187 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11188 * dolist::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11189 * dotimes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11190 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11191
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11192 @node dolist, dotimes, dolist dotimes, dolist dotimes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11193 @unnumberedsubsubsec The @code{dolist} Macro
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11194 @findex dolist
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11195
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11196 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
11197 ``first'' ``second'' ``third'' becomes ``third'' ``second'' ``first''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11198
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11199 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11200 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
11201
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11202 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11203 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11204 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11205
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11206 (reverse animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11207 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11208 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11209
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11210 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11211 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11212 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
11213
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11214 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11215 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11216 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11217
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11218 (defun reverse-list-with-while (list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11219 "Using while, reverse the order of LIST."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11220 (let (value) ; make sure list starts empty
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11221 (while list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11222 (setq value (cons (car list) value))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11223 (setq list (cdr list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11224 value))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11225
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11226 (reverse-list-with-while animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11227 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11228 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11229
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11230 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11231 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11232 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
11233
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11234 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11235 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11236 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11237
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11238 (defun reverse-list-with-dolist (list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11239 "Using dolist, reverse the order of LIST."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11240 (let (value) ; make sure list starts empty
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11241 (dolist (element list value)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11242 (setq value (cons element value)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11243
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11244 (reverse-list-with-dolist animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11245 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11246 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11247
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11248 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11249 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11250 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
11251 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
11252
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11253 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11254 (tiger lion giraffe gazelle)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11255 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11256
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11257 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11258 in the echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11259
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11260 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
11261 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
11262 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
11263 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
11264 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
11265 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
11266 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
11267 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
11268
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11269 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
11270 the @w{@code{(setq list (cdr list))}}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11271 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
11272 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
11273 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
11274 the loop.
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 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
11277 @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
11278 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
11279
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11280 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
11281 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
11282 `@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
11283 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
11284 arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11285
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11286 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
11287 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
11288 @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
11289 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
11290
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11291 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
11292 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
11293 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
11294 @code{value}.
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 @node dotimes, , dolist, dolist dotimes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11297 @unnumberedsubsubsec The @code{dotimes} Macro
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11298 @findex dotimes
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 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
11301 loops a specific number of times.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11302
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11303 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
11304 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
11305 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
11306 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
11307
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11308 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11309 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
11310 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
11311 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
11312 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
11313 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
11314
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11315 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11316 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11317 (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
11318 (dotimes (number 3 value)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11319 (setq value (cons number value))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11320
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11321 @result{} (2 1 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11322 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11323 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11326 @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
11327 @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
11328 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
11329
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11330 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11331 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
11332 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
11333
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11334 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11335 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11336 (defun triangle-using-dotimes (number-of-rows)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11337 "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
11338 (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
11339 (dotimes (number number-of-rows total)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11340 (setq total (+ total (1+ number))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11341
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11342 (triangle-using-dotimes 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11343 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11344 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11345
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11346 @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
11347 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11348 @section Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11349 @cindex Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11350
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11351 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
11352 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
11353 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
11354 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
11355 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
11356 different `instance'.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11357
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11358 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
11359 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
11360 arguments that the final instance will stop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11361
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11362 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
11363 * Building Robots:: Same model, different serial number ...
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
11364 * Recursive Definition Parts:: Walk until you stop ...
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
11365 * Recursion with list:: Using a list as the test whether to recurse.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11366 * Recursive triangle function::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11367 * Recursion with cond::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
11368 * Recursive Patterns:: Often used templates.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
11369 * No Deferment:: Don't store up work ...
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11370 * No deferment solution::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11371 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11372
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11373 @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
11374 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11375 @subsection Building Robots: Extending the Metaphor
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11376 @cindex Building robots
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11377 @cindex Robots, building
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11378
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11379 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
11380 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
11381 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
11382 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
11383 passed different arguments than the first.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11384
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11385 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
11386 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
11387 entity; but all are clones.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11388
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11389 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
11390 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
11391 when to stop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11392
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11393 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
11394
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11395 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
11396 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
11397 @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
11398 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
11399 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
11400 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
11401 but a different `serial number'.
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 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
11404 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
11405 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
11406 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
11407
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11408 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
11409 next; otherwise, the process will never stop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11410
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11411 @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
11412 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11413 @subsection The Parts of a Recursive Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11414 @cindex Parts of a Recursive Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11415 @cindex Recursive Definition Parts
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11416
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11417 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
11418 has three parts:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11419
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11420 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11421 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11422 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
11423 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
11424
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11425 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11426 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
11427 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
11428
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11429 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11430 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
11431 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
11432 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
11433 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
11434 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
11435 false after the correct number of repetitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11436 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11437
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11438 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
11439 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
11440 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
11441 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
11442 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
11443
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11444 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11445 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
11446 pattern looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11447
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11448 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11449 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11450 (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
11451 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11452 (if @var{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11453 @var{body}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11454 (@var{name-of-recursive-function}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11455 @var{next-step-expression})))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11456 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11457 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11458
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11459 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
11460 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
11461
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11462 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
11463 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
11464
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11465 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
11466
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11467 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
11468 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
11469 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
11470 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
11471 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
11472
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11473 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
11474 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
11475
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11476 @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
11477 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11478 @subsection Recursion with a List
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 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
11481 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
11482 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
11483
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
11484 If you are using GNU Emacs 20 or before, this example must be copied
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
11485 to the @file{*scratch*} buffer and each expression must be evaluated
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11486 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
11487 @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
11488 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
11489 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
11490
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11491 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
11492 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
11493 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
11494
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
11495 If you are using a more recent version of Emacs, you can evaluate this
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
11496 expression directly in Info.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11497
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11498 @findex print-elements-recursively
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11499 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11500 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11501 (setq animals '(gazelle giraffe lion tiger))
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 (defun print-elements-recursively (list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11504 "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
11505 Uses recursion."
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
11506 (when list ; @r{do-again-test}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11507 (print (car list)) ; @r{body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11508 (print-elements-recursively ; @r{recursive call}
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
11509 (cdr list)))) ; @r{next-step-expression}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11510
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11511 (print-elements-recursively animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11512 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11513 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11514
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11515 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
11516 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
11517 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
11518 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
11519 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
11520 @sc{cdr} of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11521
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11522 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
11523 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
11524 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
11525 instance.
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 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
11528 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
11529 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
11530
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
11531 When the second evaluation occurs, the @code{when} expression is
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11532 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
11533 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
11534 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
11535 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
11536 the @sc{cdr} of the original list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11537
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11538 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
11539 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
11540 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
11541 but is a separate individual.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11542
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11543 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
11544 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
11545 works on a shorter list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11546
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11547 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
11548 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
11549 tests the value of @code{list}. Since the value of @code{list} is
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
11550 @code{nil}, the @code{when} expression tests false so the then-part is
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11551 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
11552
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11553 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11554 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
11555 @file{*scratch*} buffer, you see this result:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11556
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11557 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11558 @group
45663
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
11559 gazelle
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
11560
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11561 giraffe
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11562
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11563 lion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11564
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11565 tiger
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11566 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11567 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11568 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11569
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
11570 @need 2000
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11571 @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
11572 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11573 @subsection Recursion in Place of a Counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11574 @findex triangle-recursively
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11575
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11576 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11577 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
11578 be written recursively. It looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11579
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11580 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11581 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11582 (defun triangle-recursively (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11583 "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
11584 Uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11585 (if (= number 1) ; @r{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11586 1 ; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11587 (+ number ; @r{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11588 (triangle-recursively ; @r{recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11589 (1- number))))) ; @r{next-step-expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11590
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11591 (triangle-recursively 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11592 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11593 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11596 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
11597 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
11598 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
11599 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
11600
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11601 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
11602 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
11603 its argument.
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 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11606 * Recursive Example arg of 1 or 2::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11607 * Recursive Example arg of 3 or 4::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11608 @end menu
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 @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
11611 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11612 @unnumberedsubsubsec An argument of 1 or 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11613 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11614
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11615 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
11616
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11617 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
11618 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
11619 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
11620 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
11621 one row has one pebble in it.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11622
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11623 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
11624 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
11625
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11626 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11627 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
11628 @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
11629 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11630
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11631 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11632 (+ number (triangle-recursively (1- number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11633 @end smallexample
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 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
11636 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
11637 in detail:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11638
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11639 @table @i
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11640 @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
11641
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11642 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
11643 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
11644
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11645 @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
11646
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11647 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
11648 @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
11649 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
11650 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
11651 function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11652
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11653 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
11654 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
11655 @code{triangle-recursively} returns 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11656
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11657 @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
11658
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11659 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
11660 starts with @code{+}; its value is 2.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11661
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11662 @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
11663
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11664 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
11665 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
11666 evaluation of @code{triangle-recursively} (Step 2).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11667
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11668 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
11669 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
11670 pebbles in it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11671 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11672
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11673 @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
11674 @unnumberedsubsubsec An argument of 3 or 4
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11675
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11676 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
11677 3.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11678
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11679 @table @i
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11680 @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
11681
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11682 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
11683 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
11684 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
11685 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
11686 true.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11687
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11688 @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
11689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11690 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
11691 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
11692
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11693 @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
11694
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11695 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
11696
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11697 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
11698 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
11699 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
11700
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11701 @item Step 4 @w{ } Evaluate the addition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11702
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11703 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
11704 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
11705 @end table
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11708 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
11709
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11710 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
11711 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
11712 called with an argument of 4:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11713
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11714 @quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11715 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11716 In the recursive call, the evaluation of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11717
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11718 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11719 (triangle-recursively (1- 4))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11720 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11721
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11722 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11723 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11724 will return the value of evaluating
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11725
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11726 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11727 (triangle-recursively 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11728 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11729
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11730 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11731 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
11732 third line.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11733 @end quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11734
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11735 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11736 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
11737
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11738 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
11739 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
11740 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
11741 evaluate itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11742
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11743 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
11744 requires that operations be deferred.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11745
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11746 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
11747 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
11748 @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
11749 @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
11750 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
11751 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
11752 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
11753 @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
11754
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11755 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
11756 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
11757 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
11758 on.
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 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
11761 @ref{No Deferment, , Recursion without Deferments}.
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 @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
11764 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11765 @subsection Recursion Example Using @code{cond}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11766 @findex cond
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 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
11769 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
11770 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
11771 @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
11772
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11773 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
11774 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
11775 explaining it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11776
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11777 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11778 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
11779
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11780 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11781 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11782 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11783 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11784 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11785 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11788 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
11789
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11790 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11791 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
11792
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11793 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11794 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11795 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11796 (@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
11797 (@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
11798 (@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
11799 @dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11800 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11801 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11802
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11803 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
11804 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
11805 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
11806 @code{cond}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11807
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11808 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
11809 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
11810 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
11811 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
11812 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
11813 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
11814 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
11815 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
11816 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
11817
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11818 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
11819 returns @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11820
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11821 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11822 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
11823
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11824 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11825 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11826 (defun triangle-using-cond (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11827 (cond ((<= number 0) 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11828 ((= number 1) 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11829 ((> number 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11830 (+ number (triangle-using-cond (1- number))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11831 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11832 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11833
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11834 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11835 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
11836 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
11837 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
11838 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11839
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11840 @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
11841 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11842 @subsection Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11843 @cindex Recursive Patterns
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 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
11846 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
11847 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
11848
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11849 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11850 * Every::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11851 * Accumulate::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11852 * Keep::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11853 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11854
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11855 @node Every, Accumulate, Recursive Patterns, Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11856 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11857 @unnumberedsubsubsec Recursive Pattern: @emph{every}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11858 @cindex Every, type of recursive pattern
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11859 @cindex Recursive pattern: every
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11860
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11861 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
11862 element of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11863
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11864 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11865 The basic pattern is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11866
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11867 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11868 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11869 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
11870 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11871 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
11872 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11873 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11874 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
11875 @sc{cdr}) of the list,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11876 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11877 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
11878 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
11879 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11880 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11881
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11882 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11883 Here is example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11884
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11885 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11886 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11887 (defun square-each (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11888 "Square each of a NUMBERS LIST, recursively."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11889 (if (not numbers-list) ; do-again-test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11890 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11891 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11892 (* (car numbers-list) (car numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11893 (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
11894 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11897 (square-each '(1 2 3))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11898 @result{} (1 4 9)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11899 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11900 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11901
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11902 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11903 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11904 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
11905 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
11906 with the result of the recursive call.
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 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
11909 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
11910 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
11911 empty.)
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 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
11914 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
11915 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
11916 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
11917
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11918 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11919 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
11920
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11921 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11922 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11923 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11924 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11925
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11926 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11927 (defun print-elements-recursively (list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11928 "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
11929 Uses recursion."
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
11930 (when list ; @r{do-again-test}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11931 (print (car list)) ; @r{body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11932 (print-elements-recursively ; @r{recursive call}
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
11933 (cdr list)))) ; @r{next-step-expression}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11934
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11935 (print-elements-recursively animals)
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 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11940 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
11941
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11942 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11943 @item
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
11944 When the list is empty, do nothing.
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
11945 @item
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
11946 But when the list has at least one element,
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11947 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11948 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11949 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
11950 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11951 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
11952 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11953 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11954
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11955 @node Accumulate, Keep, Every, Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11956 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11957 @unnumberedsubsubsec Recursive Pattern: @emph{accumulate}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11958 @cindex Accumulate, type of recursive pattern
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11959 @cindex Recursive pattern: accumulate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11960
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11961 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
11962 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
11963 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
11964 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
11965
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11966 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
11967 @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
11968
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11969 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11970 The pattern is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11971
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11972 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11973 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11974 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
11975 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11976 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
11977 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11978 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11979 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
11980 some other combining function, with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11981 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11982 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
11983 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11984 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11985
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11986 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11987 Here is an example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11988
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11989 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11990 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11991 (defun add-elements (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11992 "Add the elements of NUMBERS-LIST together."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11993 (if (not numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11994 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11995 (+ (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
11996 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11997
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11998 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11999 (add-elements '(1 2 3 4))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12000 @result{} 10
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12001 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12002 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12003
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12004 @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
12005 accumulate pattern.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12006
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12007 @node Keep, , Accumulate, Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12008 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12009 @unnumberedsubsubsec Recursive Pattern: @emph{keep}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12010 @cindex Keep, type of recursive pattern
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12011 @cindex Recursive pattern: keep
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12012
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12013 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
12014 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
12015 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
12016 meets a criterion.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12017
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12018 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
12019 skipped unless it meets a criterion.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12020
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12021 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12022 The pattern has three parts:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12023
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12024 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12025 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12026 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
12027 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12028 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
12029 a test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12030 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12031 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12032 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
12033 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12034 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
12035 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12036 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12037 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
12038 the test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12039 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12040 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12041 skip on that element,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12042 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12043 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
12044 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12045 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12046
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12047 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12048 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
12049
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12050 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12051 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12052 (defun keep-three-letter-words (word-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12053 "Keep three letter words in WORD-LIST."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12054 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12055 ;; First do-again-test: stop-condition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12056 ((not word-list) nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12057
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12058 ;; Second do-again-test: when to act
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12059 ((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
12060 ;; 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
12061 (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
12062
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12063 ;; 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
12064 ;; recursively call shorter list with next-step expression
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
12065 (t (keep-three-letter-words (cdr word-list)))))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12066 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12067
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12068 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12069 (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
12070 @result{} (one two six)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12071 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12072 @end smallexample
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 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
12075 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
12076
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12077 @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
12078 @subsection Recursion without Deferments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12079 @cindex Deferment in recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12080 @cindex Recursion without Deferments
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 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
12083 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
12084 deferred until all can be done.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12085
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12086 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12087 Here is the function definition:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12088
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12089 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12090 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12091 (defun triangle-recursively (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12092 "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
12093 Uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12094 (if (= number 1) ; @r{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12095 1 ; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12096 (+ number ; @r{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12097 (triangle-recursively ; @r{recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12098 (1- number))))) ; @r{next-step-expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12099 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12100 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12101
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12102 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
12103
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12104 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
12105 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
12106 @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
12107 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
12108
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12109 @smallexample
45663
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
12110 (+ 7 (triangle-recursively 6))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12111 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12112
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12113 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12114 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
12115 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
12116 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
12117 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
12118 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
12119 `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
12120 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
12121 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
12122
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12123 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
12124 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
12125 @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
12126 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
12127
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12128 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12129 Now the total is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12130
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12131 @smallexample
45663
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
12132 (+ 7 6 (triangle-recursively 5))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12133 @end smallexample
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12136 And what happens next?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12137
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12138 @smallexample
45663
046819540e6d Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents: 44899
diff changeset
12139 (+ 7 6 5 (triangle-recursively 4))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12140 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12141
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12142 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
12143 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
12144 asks it to make a calculation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12145
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12146 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12147 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
12148
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12149 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12150 (+ 7 6 5 4 3 2 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12151 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12152
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12153 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
12154 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
12155 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
12156 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
12157 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
12158 more steps.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12159
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12160 @node No deferment solution, , No Deferment, Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12161 @subsection No Deferment Solution
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12162 @cindex No deferment solution
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12163 @cindex Defermentless solution
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12164 @cindex Solution without deferment
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 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
12167 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
12168 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
12169 `constant space'.}. This requires
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12170 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
12171 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
12172 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12173
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12174 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
12175 does the work.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12176
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12177 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12178 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
12179 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
12180
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12181 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12182 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12183 (defun triangle-initialization (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12184 "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
12185 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
12186 duo that uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12187 (triangle-recursive-helper 0 0 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12188 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12189 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12190
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12191 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12192 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12193 (defun triangle-recursive-helper (sum counter number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12194 "Return SUM, using COUNTER, through NUMBER inclusive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12195 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
12196 that uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12197 (if (> counter number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12198 sum
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12199 (triangle-recursive-helper (+ sum counter) ; @r{sum}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12200 (1+ counter) ; @r{counter}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12201 number))) ; @r{number}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12202 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12203 @end smallexample
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12206 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
12207 @code{triangle-initialization} with 2 rows:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12208
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12209 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12210 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12211 (triangle-initialization 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12212 @result{} 3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12213 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12214 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12215
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12216 The `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
12217 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
12218 number of rows in the triangle.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12219
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12220 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
12221 initialization values. These values are changed when
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12222 @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
12223 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
12224 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
12225 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
12226 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
12227 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
12228 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
12229 @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
12230 `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
12231
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12232 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
12233 triangle will have one pebble in it!)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12234
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12235 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12236 @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
12237 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
12238 test whether @code{(> counter number)}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12239
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12240 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12241 (> 0 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12242 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12243
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12244 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12245 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12246 and find that the result is false, so it will invoke
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12247 the else-part of the @code{if} clause:
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12248
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12249 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12250 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12251 (triangle-recursive-helper
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12252 (+ 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
12253 (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
12254 number) ; @r{number stays the same}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12255 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12256 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12257
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12258 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12259 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12260 which will first compute:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12261
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12262 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12263 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12264 (triangle-recursive-helper (+ 0 0) ; @r{sum}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12265 (1+ 0) ; @r{counter}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12266 1) ; @r{number}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12267 @exdent which is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12268
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12269 (triangle-recursive-helper 0 1 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12270 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12271 @end smallexample
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 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
12274 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
12275 new instance with new arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12276
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12277 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12278 This new instance will be;
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12281 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12282 (triangle-recursive-helper
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12283 (+ 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
12284 (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
12285 number) ; @r{number stays the same}
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 @exdent which is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12288
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12289 (triangle-recursive-helper 1 2 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12290 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12291 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12292
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12293 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
12294 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
12295 expected.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12296
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12297 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
12298 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
12299
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12300 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
12301
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12302 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12303 In stages, the instances called will be:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12304
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12305 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12306 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12307 @r{sum counter number}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12308 (triangle-recursive-helper 0 1 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12309
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12310 (triangle-recursive-helper 1 2 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12311
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12312 (triangle-recursive-helper 3 3 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12313 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12314 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12315
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12316 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
12317 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
12318 which will be 3.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12319
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12320 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
12321 many resources in a computer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12322
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12323 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12324 @node Looping exercise, , Recursion, Loops & Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12325 @section Looping Exercise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12326
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12327 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12328 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12329 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
12330 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
12331
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12332 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12333 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
12334 adds the values.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12335
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12336 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12337 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
12338 using @code{cond}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12339
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12340 @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
12341 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12342 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
12343 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
12344 (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
12345 written in Texinfo.)
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
12346
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
12347 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
12348 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
12349 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
12350 @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
12351 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
12352 (@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
12353 backwards.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
12354
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
12355 For more information, see
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12356 @ifinfo
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
12357 @ref{Indicating, , Indicating Definitions, texinfo}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12358 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12359 @ifhtml
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
12360 @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
12361 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
12362 Internet, see
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12363 @uref{http://www.gnu.org/software/texinfo/manual/texinfo/}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12364 @end ifhtml
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12365 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12366 ``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
12367 Documentation Format}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12368 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12369 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12370
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12371 @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
12372 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12373 @chapter Regular Expression Searches
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12374 @cindex Searches, illustrating
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12375 @cindex Regular expression searches
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12376 @cindex Patterns, searching for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12377 @cindex Motion by sentence and paragraph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12378 @cindex Sentences, movement by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12379 @cindex Paragraphs, movement by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12380
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12381 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
12382 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
12383 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
12384 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
12385 as `regexp'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12386
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12387 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
12388 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
12389 @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
12390 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
12391 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
12392 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
12393 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
12394 @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
12395 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
12396 that spot.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12397
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12398 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
12399 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
12400 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
12401 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
12402 @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
12403 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
12404 @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
12405 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
12406 introduces several new features.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12407
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12408 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
12409 * sentence-end:: The regular expression for @code{sentence-end}.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
12410 * re-search-forward:: Very similar to @code{search-forward}.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
12411 * forward-sentence:: A straightforward example of regexp search.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
12412 * forward-paragraph:: A somewhat complex example.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
12413 * etags:: How to create your own @file{TAGS} table.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12414 * Regexp Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12415 * re-search Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12416 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12417
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12418 @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
12419 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12420 @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
12421 @findex sentence-end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12422
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12423 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
12424 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
12425
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12426 Clearly, a sentence may be ended by a period, a question mark, or an
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
12427 exclamation mark. Indeed, in English, only clauses that end with one
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
12428 of those three characters should be considered the end of a sentence.
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
12429 This means that the pattern should include the character set:
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12430
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12431 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12432 [.?!]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12433 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12434
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12435 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
12436 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
12437 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
12438 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
12439
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12440 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
12441 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
12442 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
12443 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
12444 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
12445 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
12446 items as alternatives.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12447
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12448 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12449 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
12450
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12451 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12452 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12453 \\($\\| \\| \\)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12454 ^ ^^
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12455 TAB SPC
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12456 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12457 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12458
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12459 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12460 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
12461 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
12462 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
12463
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12464 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
12465 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
12466 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
12467 parenthesis or the vertical bar, is special.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12468
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12469 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12470 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
12471 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12472
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12473 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12474 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12475 [
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12476 ]*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12477 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12478 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12479
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12480 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12481 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
12482 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
12483 @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
12484
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12485 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
12486 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
12487 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
12488 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
12489 expression that looks like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12492 []\"')@}]*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12493 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12494
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12495 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
12496 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
12497 @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
12498 three characters are @samp{'}, @samp{)}, and @samp{@}}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12499
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12500 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
12501 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
12502 @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
12503
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12504 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12505 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12506 sentence-end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12507 @result{} "[.?!][]\"')@}]*\\($\\| \\| \\)[
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12508 ]*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12509 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12510 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12511
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12512 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12513 (Well, not in GNU Emacs 22; that is because of an effort to make the
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
12514 process simpler and to handle more glyphs and languages. When the
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
12515 value of @code{sentence-end} is @code{nil}, then use the value defined
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
12516 by the function @code{sentence-end}. (Here is a use of the difference
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
12517 between a value and a function in Emacs Lisp.) The function returns a
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
12518 value constructed from the variables @code{sentence-end-base},
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12519 @code{sentence-end-double-space}, @code{sentence-end-without-period},
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12520 and @code{sentence-end-without-space}. The critical variable is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12521 @code{sentence-end-base}; its global value is similar to the one
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12522 described above but it also contains two additional quotation marks.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12523 These have differing degrees of curliness. The
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12524 @code{sentence-end-without-period} variable, when true, tells Emacs
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12525 that a sentence may end without a period, such as text in Thai.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12526
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12527 @ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12528 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12529 (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
12530 literally in the pattern.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12531
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
12532 This regular expression can be deciphered as follows:
41421
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 @table @code
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 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
12537 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
12538 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
12539
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12540 @item []\"')@}]*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12541 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
12542 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
12543 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
12544 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
12545 @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
12546 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
12547 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
12548 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
12549 more times.
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 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
12553 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
12554 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
12555 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
12556 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
12557 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
12558 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
12559 indicate what they are.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12560
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12561 @item [@key{RET}]*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12562 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
12563 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
12564 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
12565 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
12566 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
12567 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12568 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12569
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12570 @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
12571 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12572 @section The @code{re-search-forward} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12573 @findex re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12574
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12575 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
12576 @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
12577 @code{search-forward} Function}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12578
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12579 @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
12580 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
12581 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
12582 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
12583 @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
12584 is therefore a `side effect'.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12585
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12586 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
12587 four arguments:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12588
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12589 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12590 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12591 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
12592 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
12593
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12594 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12595 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
12596 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
12597
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12598 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12599 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
12600 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
12601 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
12602 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
12603 if the search succeeds.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12604
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12605 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12606 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
12607 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
12608 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12609
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12610 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12611 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
12612
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12613 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12614 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12615 (re-search-forward "@var{regular-expression}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12616 @var{limit-of-search}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12617 @var{what-to-do-if-search-fails}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12618 @var{repeat-count})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12619 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12620 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12621
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12622 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
12623 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
12624 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
12625 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
12626 to.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12627
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12628 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12629 In the @code{forward-sentence} function, the regular expression will be
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12630 the value of the variable @code{sentence-end}. In simple form, that is:
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12631
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12632 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12633 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12634 "[.?!][]\"')@}]*\\($\\| \\| \\)[
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12635 ]*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12636 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12637 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12638
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12639 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12640 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
12641 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
12642 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
12643 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
12644
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12645 @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
12646 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12647 @section @code{forward-sentence}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12648 @findex forward-sentence
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12649
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12650 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
12651 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
12652 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
12653 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
12654 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
12655 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
12656
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12657 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12658 * Complete forward-sentence::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
12659 * fwd-sentence while loops:: Two @code{while} loops.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
12660 * fwd-sentence re-search:: A regular expression search.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12661 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12662
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12663 @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
12664 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12665 @unnumberedsubsec Complete @code{forward-sentence} function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12666 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12667
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12668 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12669 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
12670
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12671 @c in GNU Emacs 22
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12672 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12673 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12674 (defun forward-sentence (&optional arg)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12675 "Move forward to next `sentence-end'. With argument, repeat.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12676 With negative argument, move backward repeatedly to `sentence-beginning'.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12677
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12678 The variable `sentence-end' is a regular expression that matches ends of
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12679 sentences. Also, every paragraph boundary terminates sentences as well."
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12680 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12681 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12682 (interactive "p")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12683 (or arg (setq arg 1))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12684 (let ((opoint (point))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12685 (sentence-end (sentence-end)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12686 (while (< arg 0)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12687 (let ((pos (point))
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12688 (par-beg (save-excursion (start-of-paragraph-text) (point))))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12689 (if (and (re-search-backward sentence-end par-beg t)
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12690 (or (< (match-end 0) pos)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12691 (re-search-backward sentence-end par-beg t)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12692 (goto-char (match-end 0))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12693 (goto-char par-beg)))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12694 (setq arg (1+ arg)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12695 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12696 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12697 (while (> arg 0)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12698 (let ((par-end (save-excursion (end-of-paragraph-text) (point))))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12699 (if (re-search-forward sentence-end par-end t)
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12700 (skip-chars-backward " \t\n")
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12701 (goto-char par-end)))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12702 (setq arg (1- arg)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12703 (constrain-to-field nil opoint t)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12704 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12705 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12706
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12707 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12708 GNU Emacs 21
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12709 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12710 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12711 (defun forward-sentence (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12712 "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
12713 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
12714 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
12715 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
12716 terminates sentences as well."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12717 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12718 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12719 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12720 (or arg (setq arg 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12721 (while (< arg 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12722 (let ((par-beg
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12723 (save-excursion (start-of-paragraph-text) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12724 (if (re-search-backward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12725 (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
12726 (goto-char (1- (match-end 0)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12727 (goto-char par-beg)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12728 (setq arg (1+ arg)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12729 (while (> arg 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12730 (let ((par-end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12731 (save-excursion (end-of-paragraph-text) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12732 (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
12733 (skip-chars-backward " \t\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12734 (goto-char par-end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12735 (setq arg (1- arg))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12736 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12737 @end smallexample
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12738 @end ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12739
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12740 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
12741 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
12742 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
12743
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12744 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12745 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12746 (defun forward-sentence (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12747 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12748 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12749 (or arg (setq arg 1))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12750 (let ((opoint (point)) (sentence-end (sentence-end)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12751 (while (< arg 0)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12752 (let ((pos (point))
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12753 (par-beg (save-excursion (start-of-paragraph-text) (point))))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12754 @var{rest-of-body-of-while-loop-when-going-backwards}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12755 (while (> arg 0)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12756 (let ((par-end (save-excursion (end-of-paragraph-text) (point))))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12757 @var{rest-of-body-of-while-loop-when-going-forwards}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12758 @var{handle-forms-and-equivalent}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12759 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12760 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12761
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12762 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
12763 documentation, an @code{interactive} expression, an @code{or}
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12764 expression, a @code{let} expression, and @code{while} loops.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12765
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12766 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
12767
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12768 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
12769
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12770 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
12771 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
12772 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
12773 is not passed an argument (it is optional) then the argument
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12774 @code{arg} will be bound to 1.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12775
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12776 When @code{forward-sentence} is called non-interactively without an
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12777 argument, @code{arg} is bound to @code{nil}. The @code{or} expression
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12778 handles this. What it does is either leave the value of @code{arg} as
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12779 it is, but only if @code{arg} is bound to a value; or it sets the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12780 value of @code{arg} to 1, in the case when @code{arg} is bound to
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12781 @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12782
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12783 Next is a @code{let}. That specifies the values of two local
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12784 variables, @code{point} and @code{sentence-end}. The local value of
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12785 point, from before the search, is used in the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12786 @code{constrain-to-field} function which handles forms and
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12787 equivalents. The @code{sentence-end} variable is set by the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12788 @code{sentence-end} function.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12789
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12790 @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
12791 @unnumberedsubsec The @code{while} loops
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12792
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12793 Two @code{while} loops follow. The first @code{while} has a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12794 true-or-false-test that tests true if the prefix argument for
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12795 @code{forward-sentence} is a negative number. This is for going
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12796 backwards. The body of this loop is similar to the body of the second
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12797 @code{while} clause, but it is not exactly the same. We will skip
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12798 this @code{while} loop and concentrate on the second @code{while}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12799 loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12801 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12802 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
12803 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12804
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12805 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12806 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12807 (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
12808 (let @var{varlist}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12809 (if (@var{true-or-false-test})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12810 @var{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12811 @var{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12812 (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
12813 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12814 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12815
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12816 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
12817 (@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
12818 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
12819 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
12820 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
12821 the loop repeats.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12822
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12823 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
12824 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
12825 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
12826
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12827 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
12828 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
12829 @code{if} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12830
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12831 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12832 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
12833
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12834 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12835 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12836 (let ((par-end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12837 (save-excursion (end-of-paragraph-text) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12838 (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
12839 (skip-chars-backward " \t\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12840 (goto-char par-end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12841 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12842 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12843
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12844 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
12845 @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
12846 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
12847 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
12848 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
12849
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12850 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
12851 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
12852 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
12853 evaluates the expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12854
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12855 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12856 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12857 (save-excursion (end-of-paragraph-text) (point))
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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12861 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12862 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
12863 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
12864 @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
12865 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
12866 @code{save-excursion} expression, which is the position of the end of
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
12867 the paragraph. (The @code{end-of-paragraph-text} function uses
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12868 @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
12869
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12870 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12871 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
12872 expression that looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12873
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12874 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12875 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12876 (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
12877 (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
12878 (goto-char par-end))) ; @r{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12879 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12880 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12881
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12882 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
12883 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
12884 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
12885 expression is the regular expression search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12886
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12887 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
12888 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
12889 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
12890
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12891 @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
12892 @unnumberedsubsec The regular expression search
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12893
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12894 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
12895 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
12896 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
12897 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
12898
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12899 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12900 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12901 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
12902 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
12903
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12904 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12905 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
12906 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
12907 successful.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12908 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12909
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12910 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12911 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
12912 @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
12913 conclusion of the search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12914
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12915 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
12916 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
12917 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
12918 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
12919 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
12920 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
12921 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
12922 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
12923 usually a period.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12924
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12925 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
12926 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
12927 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
12928 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
12929 end of the paragraph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12930
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12931 (And if the text is in a form or equivalent, and point may not move
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12932 fully, then the @code{constrain-to-field} function comes into play.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12933
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12934 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
12935 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
12936 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
12937 incorporating this pattern often.
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 @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
12940 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12941 @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
12942 @findex forward-paragraph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12943
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12944 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12945 @c in GNU Emacs 22
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12946 (defun forward-paragraph (&optional arg)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12947 "Move forward to end of paragraph.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12948 With argument ARG, do it ARG times;
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12949 a negative argument ARG = -N means move backward N paragraphs.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12950
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12951 A line which `paragraph-start' matches either separates paragraphs
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12952 \(if `paragraph-separate' matches it also) or is the first line of a paragraph.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12953 A paragraph end is the beginning of a line which is not part of the paragraph
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12954 to which the end of the previous line belongs, or the end of the buffer.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12955 Returns the count of paragraphs left to move."
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12956 (interactive "p")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12957 (or arg (setq arg 1))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12958 (let* ((opoint (point))
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12959 (fill-prefix-regexp
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12960 (and fill-prefix (not (equal fill-prefix ""))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12961 (not paragraph-ignore-fill-prefix)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12962 (regexp-quote fill-prefix)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12963 ;; Remove ^ from paragraph-start and paragraph-sep if they are there.
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12964 ;; These regexps shouldn't be anchored, because we look for them
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12965 ;; starting at the left-margin. This allows paragraph commands to
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12966 ;; work normally with indented text.
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12967 ;; This hack will not find problem cases like "whatever\\|^something".
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12968 (parstart (if (and (not (equal "" paragraph-start))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12969 (equal ?^ (aref paragraph-start 0)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12970 (substring paragraph-start 1)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12971 paragraph-start))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12972 (parsep (if (and (not (equal "" paragraph-separate))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12973 (equal ?^ (aref paragraph-separate 0)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12974 (substring paragraph-separate 1)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12975 paragraph-separate))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12976 (parsep
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12977 (if fill-prefix-regexp
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12978 (concat parsep "\\|"
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12979 fill-prefix-regexp "[ \t]*$")
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12980 parsep))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12981 ;; This is used for searching.
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12982 (sp-parstart (concat "^[ \t]*\\(?:" parstart "\\|" parsep "\\)"))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12983 start found-start)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12984 (while (and (< arg 0) (not (bobp)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
12985 (if (and (not (looking-at parsep))
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12986 (re-search-backward "^\n" (max (1- (point)) (point-min)) t)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12987 (looking-at parsep))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12988 (setq arg (1+ arg))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12989 (setq start (point))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12990 ;; Move back over paragraph-separating lines.
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12991 (forward-char -1) (beginning-of-line)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12992 (while (and (not (bobp))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12993 (progn (move-to-left-margin)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12994 (looking-at parsep)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12995 (forward-line -1))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12996 (if (bobp)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12997 nil
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12998 (setq arg (1+ arg))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
12999 ;; Go to end of the previous (non-separating) line.
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13000 (end-of-line)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13001 ;; Search back for line that starts or separates paragraphs.
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13002 (if (if fill-prefix-regexp
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13003 ;; There is a fill prefix; it overrides parstart.
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13004 (let (multiple-lines)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13005 (while (and (progn (beginning-of-line) (not (bobp)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13006 (progn (move-to-left-margin)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13007 (not (looking-at parsep)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13008 (looking-at fill-prefix-regexp))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13009 (unless (= (point) start)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13010 (setq multiple-lines t))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13011 (forward-line -1))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13012 (move-to-left-margin)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13013 ;; This deleted code caused a long hanging-indent line
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13014 ;; not to be filled together with the following lines.
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13015 ;; ;; Don't move back over a line before the paragraph
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13016 ;; ;; which doesn't start with fill-prefix
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13017 ;; ;; unless that is the only line we've moved over.
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13018 ;; (and (not (looking-at fill-prefix-regexp))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13019 ;; multiple-lines
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13020 ;; (forward-line 1))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13021 (not (bobp)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13022 (while (and (re-search-backward sp-parstart nil 1)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13023 (setq found-start t)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13024 ;; Found a candidate, but need to check if it is a
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13025 ;; REAL parstart.
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13026 (progn (setq start (point))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13027 (move-to-left-margin)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13028 (not (looking-at parsep)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13029 (not (and (looking-at parstart)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13030 (or (not use-hard-newlines)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13031 (bobp)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13032 (get-text-property
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13033 (1- start) 'hard)))))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13034 (setq found-start nil)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13035 (goto-char start))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13036 found-start)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13037 ;; Found one.
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13038 (progn
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13039 ;; Move forward over paragraph separators.
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13040 ;; We know this cannot reach the place we started
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13041 ;; because we know we moved back over a non-separator.
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13042 (while (and (not (eobp))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13043 (progn (move-to-left-margin)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13044 (looking-at parsep)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13045 (forward-line 1))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13046 ;; If line before paragraph is just margin, back up to there.
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13047 (end-of-line 0)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13048 (if (> (current-column) (current-left-margin))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13049 (forward-char 1)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13050 (skip-chars-backward " \t")
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13051 (if (not (bolp))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13052 (forward-line 1))))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13053 ;; No starter or separator line => use buffer beg.
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13054 (goto-char (point-min))))))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13055
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13056 (while (and (> arg 0) (not (eobp)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13057 ;; Move forward over separator lines...
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13058 (while (and (not (eobp))
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13059 (progn (move-to-left-margin) (not (eobp)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13060 (looking-at parsep))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13061 (forward-line 1))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13062 (unless (eobp) (setq arg (1- arg)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13063 ;; ... and one more line.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13064 (forward-line 1)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13065 (if fill-prefix-regexp
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13066 ;; There is a fill prefix; it overrides parstart.
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13067 (while (and (not (eobp))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13068 (progn (move-to-left-margin) (not (eobp)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13069 (not (looking-at parsep))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13070 (looking-at fill-prefix-regexp))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13071 (forward-line 1))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13072 (while (and (re-search-forward sp-parstart nil 1)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13073 (progn (setq start (match-beginning 0))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13074 (goto-char start)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13075 (not (eobp)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13076 (progn (move-to-left-margin)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13077 (not (looking-at parsep)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13078 (or (not (looking-at parstart))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13079 (and use-hard-newlines
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13080 (not (get-text-property (1- start) 'hard)))))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13081 (forward-char 1))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13082 (if (< (point) (point-max))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
13083 (goto-char start))))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13084 (constrain-to-field nil opoint t)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13085 ;; Return the number of steps that could not be done.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13086 arg))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13087 @end ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13088
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13089 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
13090 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
13091 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
13092 @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
13093
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13094 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
13095 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
13096 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
13097 fill prefix.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13098
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13099 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
13100 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
13101 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
13102 @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
13103 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
13104 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
13105 prefixes.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13106
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13107 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
13108 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
13109 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
13110 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
13111 with the fill prefix.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13112
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13113 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
13114 exists, especially when blank lines separate paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13115 This is an added complication.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13116
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13117 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
13118 * forward-paragraph in brief:: Key parts of the function definition.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
13119 * fwd-para let:: The @code{let*} expression.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
13120 * fwd-para while:: The forward motion @code{while} loop.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13121 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13122
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13123 @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
13124 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13125 @unnumberedsubsec Shortened @code{forward-paragraph} function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13126 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13127
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13128 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
13129 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
13130 can be daunting!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13131
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13132 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13133 In outline, the function looks like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13136 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13137 (defun forward-paragraph (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13138 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13139 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13140 (or arg (setq arg 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13141 (let*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13142 @var{varlist}
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13143 (while (and (< arg 0) (not (bobp))) ; @r{backward-moving-code}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13144 @dots{}
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13145 (while (and (> arg 0) (not (eobp))) ; @r{forward-moving-code}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13146 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13147 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13148 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13149
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13150 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
13151 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
13152
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13153 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
13154 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
13155 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
13156 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
13157 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
13158 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
13159 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
13160 @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
13161 familiar part of this function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13162
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13163 @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
13164 @unnumberedsubsec The @code{let*} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13165
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13166 The next line of the @code{forward-paragraph} function begins a
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13167 @code{let*} expression. This is a different than @code{let}. The
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13168 symbol is @code{let*} not @code{let}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13169
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13170 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
13171 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
13172 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
13173 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
13174
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13175 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13176 ( refappend save-excursion, , code save-excursion in code append-to-buffer .)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13177 @end ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13178
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13179 (@ref{append save-excursion, , @code{save-excursion} in @code{append-to-buffer}}.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13180
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13181 In the @code{let*} expression in this function, Emacs binds a total of
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13182 seven variables: @code{opoint}, @code{fill-prefix-regexp},
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13183 @code{parstart}, @code{parsep}, @code{sp-parstart}, @code{start}, and
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13184 @code{found-start}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13185
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13186 The variable @code{parsep} appears twice, first, to remove instances
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13187 of @samp{^}, and second, to handle fill prefixes.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13188
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13189 The variable @code{opoint} is just the value of @code{point}. As you
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13190 can guess, it is used in a @code{constrain-to-field} expression, just
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13191 as in @code{forward-sentence}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13192
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13193 The variable @code{fill-prefix-regexp} is set to the value returned by
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13194 evaluating the following list:
41421
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13197 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13198 (and fill-prefix
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13199 (not (equal fill-prefix ""))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13200 (not paragraph-ignore-fill-prefix)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13201 (regexp-quote fill-prefix))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13202 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13203 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13204
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13205 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13206 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
13207
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13208 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
13209 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
13210 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
13211 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
13212 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
13213 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
13214 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
13215 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
13216 arguments are true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13217 @findex and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13218
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13219 In 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
13220 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
13221 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
13222 @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
13223
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13224 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13225 @item fill-prefix
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13226 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
13227 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
13228 @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13229
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13230 @item (not (equal fill-prefix "")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13231 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
13232 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
13233 not a useful fill prefix.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13234
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13235 @item (not paragraph-ignore-fill-prefix)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13236 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
13237 @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
13238 true value such as @code{t}.
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 @item (regexp-quote fill-prefix)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13241 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
13242 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
13243 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
13244 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
13245 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13246
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13247 @findex regexp-quote
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13248 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13249 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
13250 @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
13251 @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
13252 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
13253 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
13254 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
13255 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
13256 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
13257
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13258 The next two local variables in the @code{let*} expression are
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13259 designed to remove instances of @samp{^} from @code{parstart} and
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13260 @code{parsep}, the local variables which indicate the paragraph start
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13261 and the paragraph separator. The next expression sets @code{parsep}
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13262 again. That is to handle fill prefixes.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13263
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13264 This is the setting that requires the definition call @code{let*}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13265 rather than @code{let}. The true-or-false-test for the @code{if}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13266 depends on whether the variable @code{fill-prefix-regexp} evaluates to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13267 @code{nil} or some other value.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13268
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13269 If @code{fill-prefix-regexp} does not have a value, Emacs evaluates
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13270 the else-part of the @code{if} expression and binds @code{parsep} to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13271 its local value. (@code{parsep} is a regular expression that matches
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13272 what separates paragraphs.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13273
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13274 But if @code{fill-prefix-regexp} does have a value, Emacs evaluates
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13275 the then-part of the @code{if} expression and binds @code{parsep} to a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13276 regular expression that includes the @code{fill-prefix-regexp} as part
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13277 of the pattern.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13278
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13279 Specifically, @code{parsep} is set to the original value of the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13280 paragraph separate regular expression concatenated with an alternative
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13281 expression that consists of the @code{fill-prefix-regexp} followed by
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13282 optional whitespace to the end of the line. The whitespace is defined
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13283 by @w{@code{"[ \t]*$"}}.) The @samp{\\|} defines this portion of the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13284 regexp as an alternative to @code{parsep}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13285
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13286 According to a comment in the code, the next local variable,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13287 @code{sp-parstart}, is used for searching, and then the final two,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13288 @code{start} and @code{found-start}, are set to @code{nil}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13289
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13290 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
13291 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
13292 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
13293 section.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13294
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13295 @node fwd-para while, , fwd-para let, forward-paragraph
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13296 @unnumberedsubsec The forward motion @code{while} loop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13297
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13298 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
13299 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
13300 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
13301 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
13302 @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
13303 forward one paragraph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13304
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13305 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13306 (while (and (> arg 0) (not (eobp)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13307
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13308 ;; Move forward over separator lines...
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13309 (while (and (not (eobp))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13310 (progn (move-to-left-margin) (not (eobp)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13311 (looking-at parsep))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13312 (forward-line 1))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13313 (unless (eobp) (setq arg (1- arg)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13314 ;; ... and one more line.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13315 (forward-line 1)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13316
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13317 (if fill-prefix-regexp
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13318 ;; There is a fill prefix; it overrides parstart.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13319 (while (and (not (eobp))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13320 (progn (move-to-left-margin) (not (eobp)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13321 (not (looking-at parsep))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13322 (looking-at fill-prefix-regexp))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13323 (forward-line 1))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13324
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13325 (while (and (re-search-forward sp-parstart nil 1)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13326 (progn (setq start (match-beginning 0))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13327 (goto-char start)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13328 (not (eobp)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13329 (progn (move-to-left-margin)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13330 (not (looking-at parsep)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13331 (or (not (looking-at parstart))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13332 (and use-hard-newlines
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13333 (not (get-text-property (1- start) 'hard)))))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13334 (forward-char 1))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13335
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13336 (if (< (point) (point-max))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13337 (goto-char start))))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13338 @end ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13339
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13340 This part handles three situations: when point is between paragraphs,
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13341 when there is a fill prefix and when there is no fill prefix.
41421
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13344 The @code{while} loop looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13345
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13346 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13347 @group
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13348 ;; @r{going forwards and not at the end of the buffer}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13349 (while (and (> arg 0) (not (eobp)))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13350
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13351 ;; @r{between paragraphs}
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13352 ;; Move forward over separator lines...
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13353 (while (and (not (eobp))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13354 (progn (move-to-left-margin) (not (eobp)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13355 (looking-at parsep))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13356 (forward-line 1))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13357 ;; @r{This decrements the loop}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13358 (unless (eobp) (setq arg (1- arg)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13359 ;; ... and one more line.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13360 (forward-line 1)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13361 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13362
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13363 @group
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13364 (if fill-prefix-regexp
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13365 ;; There is a fill prefix; it overrides parstart;
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13366 ;; we go forward line by line
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13367 (while (and (not (eobp))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13368 (progn (move-to-left-margin) (not (eobp)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13369 (not (looking-at parsep))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13370 (looking-at fill-prefix-regexp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13371 (forward-line 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13372 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13373
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13374 @group
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13375 ;; There is no fill prefix;
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13376 ;; we go forward character by character
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13377 (while (and (re-search-forward sp-parstart nil 1)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13378 (progn (setq start (match-beginning 0))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13379 (goto-char start)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13380 (not (eobp)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13381 (progn (move-to-left-margin)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13382 (not (looking-at parsep)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13383 (or (not (looking-at parstart))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13384 (and use-hard-newlines
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13385 (not (get-text-property (1- start) 'hard)))))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13386 (forward-char 1))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13387 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13388
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13389 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13390 ;; and if there is no fill prefix and if we are not at the end,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13391 ;; go to whatever was found in the regular expression search
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13392 ;; for sp-parstart
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13393 (if (< (point) (point-max))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13394 (goto-char start))))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13395 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13396 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13397
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13398 @findex eobp
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13399 We can see that this is a decrementing counter @code{while} loop,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13400 using the expression @code{(setq arg (1- arg))} as the decrementer.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13401 That expression is not far from the @code{while}, but is hidden in
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13402 another Lisp macro, an @code{unless} macro. Unless we are at the end
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13403 of the buffer --- that is what the @code{eobp} function determines; it
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13404 is an abbreviation of @samp{End Of Buffer P} --- we decrease the value
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13405 of @code{arg} by one.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13406
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13407 (If we are at the end of the buffer, we cannot go forward any more and
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13408 the next loop of the @code{while} expression will test false since the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13409 test is an @code{and} with @code{(not (eobp))}. The @code{not}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13410 function means exactly as you expect; it is another name for
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13411 @code{null}, a function that returns true when its argument is false.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13412
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13413 Interestingly, the loop count is not decremented until we leave the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13414 space between paragraphs, unless we come to the end of buffer or stop
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13415 seeing the local value of the paragraph separator.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13416
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13417 That second @code{while} also has a @code{(move-to-left-margin)}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13418 expression. The function is self-explanatory. It is inside a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13419 @code{progn} expression and not the last element of its body, so it is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13420 only invoked for its side effect, which is to move point to the left
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13421 margin of the current line.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13422
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13423 @findex looking-at
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13424 The @code{looking-at} function is also self-explanatory; it returns
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13425 true if the text after point matches the regular expression given as
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13426 its argument.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13427
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13428 The rest of the body of the loop looks difficult at first, but makes
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13429 sense as you come to understand it.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13430
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13431 @need 800
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13432 First consider what happens if there is a fill prefix:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13433
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13434 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13435 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13436 (if fill-prefix-regexp
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13437 ;; There is a fill prefix; it overrides parstart;
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13438 ;; we go forward line by line
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13439 (while (and (not (eobp))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13440 (progn (move-to-left-margin) (not (eobp)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13441 (not (looking-at parsep))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13442 (looking-at fill-prefix-regexp))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13443 (forward-line 1))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13444 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13445 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13446
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13447 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13448 This expression moves point forward line by line so long
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13449 as four conditions are true:
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13450
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13451 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13452 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13453 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
13454
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13455 @item
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13456 We can move to the left margin of the text and are
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13457 not at the end of the buffer.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13458
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13459 @item
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13460 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
13461
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13462 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13463 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
13464 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13465
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13466 The 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
13467 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
13468 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
13469 @code{looking-at} function will see it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13470
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13471 @need 1250
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13472 Consider what happens when there is no fill prefix.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13473
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13474 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13475 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13476 (while (and (re-search-forward sp-parstart nil 1)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13477 (progn (setq start (match-beginning 0))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13478 (goto-char start)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13479 (not (eobp)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13480 (progn (move-to-left-margin)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13481 (not (looking-at parsep)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13482 (or (not (looking-at parstart))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13483 (and use-hard-newlines
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13484 (not (get-text-property (1- start) 'hard)))))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13485 (forward-char 1))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13486 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13487 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13488
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13489 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13490 This @code{while} loop has us searching forward for
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13491 @code{sp-parstart}, which is the combination of possible whitespace
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13492 with a the local value of the start of a paragraph or of a paragraph
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13493 separator. (The latter two are within an expression starting
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13494 @code{\(?:} so that they are not referenced by the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13495 @code{match-beginning} function.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13496
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13497 @need 800
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13498 The two expressions,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13499
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13500 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13501 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13502 (setq start (match-beginning 0))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13503 (goto-char start)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13504 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13505 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13506
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13507 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13508 mean go to the start of the text matched by the regular expression
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13509 search.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13510
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13511 The @code{(match-beginning 0)} expression is new. It returns a number
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13512 specifying the location of the start of the text that was matched by
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13513 the last search.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13514
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13515 The @code{match-beginning} function is used here because of a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13516 characteristic of a forward search: a successful forward search,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13517 regardless of whether it is a plain search or a regular expression
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13518 search, moves point to the end of the text that is found. In this
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13519 case, a successful search moves point to the end of the pattern for
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13520 @code{sp-parstart}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13521
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13522 However, we want to put point at the end of the current paragraph, not
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13523 somewhere else. Indeed, since the search possibly includes the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13524 paragraph separator, point may end up at the beginning of the next one
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13525 unless we use an expression that includes @code{match-beginning}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13526
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13527 @findex match-beginning
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13528 When given an argument of 0, @code{match-beginning} returns the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13529 position that is the start of the text matched by the most recent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13530 search. In this case, the most recent search looks for
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13531 @code{sp-parstart}. The @code{(match-beginning 0)} expression returns
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13532 the beginning position of that pattern, rather than the end position
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13533 of that pattern.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13534
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13535 (Incidentally, when passed a positive number as an argument, the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13536 @code{match-beginning} function returns the location of point at that
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13537 parenthesized expression in the last search unless that parenthesized
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13538 expression begins with @code{\(?:}. I don't know why @code{\(?:}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13539 appears here since the argument is 0.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13540
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13541 @need 1250
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13542 The last expression when there is no fill prefix is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13543
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13544 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13545 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13546 (if (< (point) (point-max))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13547 (goto-char start))))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13548 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13549 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13550
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13551 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13552 This says that if there is no fill prefix and if we are not at the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13553 end, point should move to the beginning of whatever was found by the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13554 regular expression search for @code{sp-parstart}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13555
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13556 The full definition for the @code{forward-paragraph} function not only
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13557 includes code for going forwards, but also code for going backwards.
41421
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 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
13560 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
13561 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
13562 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
13563 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
13564 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
13565 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
13566 a car with his eyes shut!)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13567
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13568 @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
13569 @section Create Your Own @file{TAGS} File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13570 @findex etags
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13571 @cindex @file{TAGS} file, create own
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13572
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13573 Besides @kbd{C-h f} (@code{describe-function}), another way to see the
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13574 source of a function is to type @kbd{M-.} (@code{find-tag}) and the
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13575 name of the function when prompted for it. This is a good habit to
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13576 get into. The @kbd{M-.} (@code{find-tag}) command takes you directly
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13577 to the source for a function, variable, or node. The function depends
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13578 on tags tables to tell it where to go.
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13579
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13580 If the @code{find-tag} function first asks you for the name of a
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13581 @file{TAGS} table, give it the name of a @file{TAGS} file such as
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13582 @file{/usr/local/src/emacs/src/TAGS}. (The exact path to your
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13583 @file{TAGS} file depends on how your copy of Emacs was installed. I
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13584 just told you the location that provides both my C and my Emacs Lisp
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13585 sources.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13586
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13587 You can also create your own @file{TAGS} file for directories that
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13588 lack one.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13589
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13590 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
13591 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
13592 the name is in upper case letters.
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 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
13595 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
13596 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
13597 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
13598
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13599 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13600 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
13601 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
13602 @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
13603 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
13604 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
13605
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13606 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13607 M-x compile RET etags *.el RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13608 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13609
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13610 @noindent
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13611 to create a @file{TAGS} file for Emacs Lisp.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13612
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13613 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
13614 @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
13615 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
13616 Lisp files in that directory.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13617
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13618 @need 1250
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13619 The @code{etags} program takes all the usual shell `wildcards'. For
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13620 example, if you have two directories for which you want a single
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13621 @file{TAGS} file, type @w{@code{etags *.el ../elisp/*.el}}, where
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13622 @file{../elisp/} is the second directory:
41421
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13625 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
13626 @end smallexample
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13629 Type
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13630
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13631 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13632 M-x compile RET etags --help RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13633 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13634
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13635 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13636 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
13637 list of supported languages.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13638
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13639 The @code{etags} program handles more than 20 languages, including
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13640 Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, HTML, Java,
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13641 LaTeX, Pascal, Perl, Postscript, Python, TeX, Texinfo, makefiles, and
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13642 most assemblers. The program has no switches for specifying the
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13643 language; it recognizes the language in an input file according to its
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13644 file name and contents.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13645
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13646 @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
13647 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
13648 @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
13649 become part of the @file{TAGS} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13650
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13651 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
13652 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
13653 program to attempt to find it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13654
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13655 Type @w{@kbd{M-x locate @key{RET} TAGS @key{RET}}} and Emacs will list
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13656 for you the full path names of all your @file{TAGS} files. On my
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13657 system, this command lists 34 @file{TAGS} files. On the other hand, a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13658 `plain vanilla' system I recently installed did not contain any
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13659 @file{TAGS} files.
41421
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 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
13662 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
13663 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
13664 visit-tags-table}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13665
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13666 @subsubheading Building Tags in the Emacs sources
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13667 @cindex Building Tags in the Emacs sources
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13668 @cindex Tags in the Emacs sources
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13669 @findex make tags
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13670
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13671 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
13672 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
13673 tags tables from all over the Emacs sources and puts the information
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13674 into one @file{TAGS} file in the @file{src/} directory. (The
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13675 @file{src/} directory is below the top level of your Emacs directory.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13676
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13677 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13678 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
13679 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
13680
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13681 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13682 M-x compile RET make tags RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13683 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13686 (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
13687 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
13688
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13689 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
13690 Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13691
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13692 @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
13693 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13694 @section Review
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 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
13697
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13698 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13699 @item while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13700 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
13701 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
13702 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
13703
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13704 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13705 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13706
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13707 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13708 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13709 (let ((foo 2))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13710 (while (> foo 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13711 (insert (format "foo is %d.\n" foo))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13712 (setq foo (1- foo))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13713
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13714 @result{} foo is 2.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13715 foo is 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13716 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13717 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13718 @end smallexample
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13719
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13720 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13721 (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
13722 @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
13723 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
13724 line.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13725
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13726 @item re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13727 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
13728 just after it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13729
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13730 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13731 Takes four arguments, like @code{search-forward}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13732
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13733 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13734 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13735 A regular expression that specifies the pattern to search for.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13736 (Remember to put quotation marks around this argument!)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13737
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13738 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13739 Optionally, the limit of the search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13740
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13741 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13742 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
13743 error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13744
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13745 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13746 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
13747 search goes backwards.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13748 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13749
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13750 @item let*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13751 Bind some variables locally to particular values,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13752 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
13753 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
13754 variables bound earlier, if any.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13757 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13758
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13759 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13760 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13761 (let* ((foo 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13762 (bar (* 3 foo)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13763 (message "`bar' is %d." bar))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13764 @result{} `bar' is 21.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13765 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13766 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13767
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13768 @item match-beginning
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13769 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
13770 expression search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13771
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13772 @item looking-at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13773 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
13774 which should be a regular expression.
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 @item eobp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13777 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
13778 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
13779 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
13780 the buffer is narrowed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13781 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13782
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13783 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13784 @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
13785 @section Exercises with @code{re-search-forward}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13786
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13787 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13788 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13789 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
13790 or more blank lines in sequence.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13791
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13792 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13793 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
13794 @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
13795 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
13796 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
13797 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
13798 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
13799 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
13800 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13801
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13802 @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
13803 @chapter Counting: Repetition and Regexps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13804 @cindex Repetition for word counting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13805 @cindex Regular expressions for word counting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13806
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13807 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
13808 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
13809 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
13810 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
13811
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13812 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13813 * Why Count Words::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
13814 * count-words-region:: Use a regexp, but find a problem.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
13815 * recursive-count-words:: Start with case of no words in region.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13816 * Counting Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13817 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13818
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13819 @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
13820 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13821 @unnumberedsec Counting words
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13822 @end ifnottex
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 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
13825 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
13826 function for counting words.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13827
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13828 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
13829 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
13830 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
13831 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
13832 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
13833 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
13834 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
13835 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
13836 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
13837 commands to count words.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13838
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13839 @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
13840 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13841 @section The @code{count-words-region} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13842 @findex count-words-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13843
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13844 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
13845 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
13846 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
13847 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
13848 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
13849 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
13850 region. Once you have a @code{count-words-region} command, you can,
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13851 if you wish, count words in a whole buffer by marking it with
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13852 @w{@kbd{C-x h}} (@code{mark-whole-buffer}).
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13853
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13854 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
13855 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
13856 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
13857 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
13858 or to a @code{while} loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13859
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13860 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
13861 * Design count-words-region:: The definition using a @code{while} loop.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
13862 * Whitespace Bug:: The Whitespace Bug in @code{count-words-region}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13863 @end menu
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 @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
13866 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13867 @unnumberedsubsec Designing @code{count-words-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13868 @end ifnottex
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 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
13871 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
13872 interactive.
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13875 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
13876
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13877 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13878 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13879 (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
13880 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13881 (@var{interactive-expression}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13882 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13883 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13884 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13885
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13886 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
13887
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13888 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
13889 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
13890 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
13891
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13892 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
13893 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
13894 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
13895 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
13896 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
13897 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
13898 @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
13899 @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
13900 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
13901 this is routine.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13902
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13903 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
13904 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
13905 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
13906 a message to the user.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13907
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13908 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
13909 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
13910 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
13911 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
13912 @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
13913 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
13914 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
13915 @code{save-excursion} expression.
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 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
13918 @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
13919 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
13920 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
13921 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
13922
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13923 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
13924 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
13925 `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
13926
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13927 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
13928 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
13929 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
13930 word by word.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13931
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13932 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
13933 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
13934 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
13935 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
13936 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
13937 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
13938 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
13939 the regexp must be optional.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13940
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13941 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
13942 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
13943 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
13944 this is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13945
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13946 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13947 \w+\W*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13948 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13949
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13950 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13951 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
13952 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
13953 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
13954 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
13955 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
13956
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13957 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13958 The search expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13959
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13960 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13961 (re-search-forward "\\w+\\W*")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13962 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13963
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13964 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13965 (Note that paired backslashes precede the @samp{w} and @samp{W}. A
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13966 single backslash has special meaning to the Emacs Lisp interpreter.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13967 It indicates that the following character is interpreted differently
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
13968 than usual. For example, the two characters, @samp{\n}, stand for
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13969 @samp{newline}, rather than for a backslash followed by @samp{n}. Two
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13970 backslashes in a row stand for an ordinary, `unspecial' backslash, so
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13971 Emacs Lisp interpreter ends of seeing a single backslash followed by a
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
13972 letter. So it discovers the letter is special.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13973
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13974 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
13975 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
13976 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
13977
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13978 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13979 (setq count (1+ count))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13980 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13981
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13982 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
13983 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
13984 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
13985 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
13986 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
13987 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
13988 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
13989 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
13990 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
13991 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
13992 special form is appropriate.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13993
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13994 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13995 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
13996
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13997 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13998 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13999 ;;; @r{First version; has bugs!}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14000 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14001 "Print number of words in the region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14002 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
14003 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
14004 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
14005 table determines which characters these are."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14006 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14007 (message "Counting words in region ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14008 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14009
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14010 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14011 ;;; @r{1. Set up appropriate conditions.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14012 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14013 (goto-char beginning)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14014 (let ((count 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14015 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14016
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14017 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14018 ;;; @r{2. Run the} while @r{loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14019 (while (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14020 (re-search-forward "\\w+\\W*")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14021 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14022 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14023
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14024 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14025 ;;; @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
14026 (cond ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14027 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14028 "The region does NOT have any words."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14029 ((= 1 count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14030 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14031 "The region has 1 word."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14032 (t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14033 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14034 "The region has %d words." count))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14035 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14036 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14037
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14038 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14039 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
14040
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14041 @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
14042 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14043 @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
14044
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14045 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
14046 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
14047 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
14048 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
14049 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
14050 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
14051 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
14052 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14053
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14054 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14055 Search failed: "\\w+\\W*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14056 @end smallexample
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 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
14059 bugs yourself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14060
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14061 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
14062 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14063 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
14064 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
14065
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14066 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14067 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14068 ;; @r{First version; has bugs!}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14069 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14070 "Print number of words in the region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14071 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
14072 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
14073 syntax table determines which characters these are."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14074 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14075 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14076 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14077 (message "Counting words in region ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14078 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14079
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14080 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14081 ;;; @r{1. Set up appropriate conditions.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14082 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14083 (goto-char beginning)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14084 (let ((count 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14085 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14086
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14087 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14088 ;;; @r{2. Run the} while @r{loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14089 (while (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14090 (re-search-forward "\\w+\\W*")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14091 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14092 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14093
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14094 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14095 ;;; @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
14096 (cond ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14097 (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
14098 ((= 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
14099 (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
14100 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14101 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14102 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14103
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14104 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14105 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
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 (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
14109 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14110
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14111 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
14112 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
14113 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
14114
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14115 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14116 one two three
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14117 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14118
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14119 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14120 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
14121
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14122 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
14123 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
14124 @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
14125 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
14126 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
14127 that the region has one word!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14128
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14129 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
14130 @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
14131 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
14132 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
14133 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
14134 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
14135 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
14136 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
14137
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14138 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
14139
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14140 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
14141 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
14142 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
14143 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
14144 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
14145 @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
14146 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
14147 @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
14148 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
14149 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
14150 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
14151 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
14152 the marked region.
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 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
14155 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
14156 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
14157 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
14158 in the buffer, the search fails.
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 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
14161 extend outside of the region.
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 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
14164 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
14165 simple as you might think.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14166
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14167 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
14168 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
14169 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
14170 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
14171 @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
14172 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
14173 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
14174 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
14175
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14176 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
14177 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
14178 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
14179 to the regular expression search expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14180
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14181 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14182 (re-search-forward "\\w+\\W*" end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14183 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14184
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14185 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
14186 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
14187 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
14188 @samp{Search failed}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14189
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14190 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
14191 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
14192 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
14193 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
14194 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
14195
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14196 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
14197 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
14198 @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
14199
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14200 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
14201 ``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
14202 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
14203
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14204 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
14205 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
14206 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
14207 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
14208 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
14209 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
14210 @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
14211 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
14212 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
14213 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
14214 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
14215
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14216 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
14217 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
14218 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
14219 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
14220 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
14221 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
14222
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14223 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
14224 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
14225 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
14226 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
14227
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14228 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14229 (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
14230 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14231
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14232 @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
14233 @c also trouble with an overfull hbox
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14234 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14235 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14236 (For information about @code{and}, see
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
14237 @ref{kill-new function, , The @code{kill-new} function}.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14238 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14239 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14240 @noindent
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
14241 (@xref{kill-new function, , The @code{kill-new} function}, for
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
14242 information about @code{and}.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14243 @end ifinfo
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 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
14246 succeeds and as a side effect moves point. Consequently, as words are
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
14247 found, point is moved through the region. When the search expression
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
14248 fails to find another word, or when point reaches the end of the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
14249 region, the true-or-false-test tests false, the @code{while} loop
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
14250 exits, and the @code{count-words-region} function displays one or
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
14251 other of its messages.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14252
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14253 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
14254 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
14255 Here is what it looks like:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14256
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14257 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14258 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14259 ;;; @r{Final version:} @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14260 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14261 "Print number of words in the region."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14262 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14263 (message "Counting words in region ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14264 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14265
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14266 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14267 ;;; @r{1. Set up appropriate conditions.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14268 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14269 (let ((count 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14270 (goto-char beginning)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14271 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14272
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14273 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14274 ;;; @r{2. Run the} while @r{loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14275 (while (and (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14276 (re-search-forward "\\w+\\W*" end t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14277 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14278 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14279
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14280 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14281 ;;; @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
14282 (cond ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14283 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14284 "The region does NOT have any words."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14285 ((= 1 count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14286 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14287 "The region has 1 word."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14288 (t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14289 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14290 "The region has %d words." count))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14291 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14292 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14293
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14294 @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
14295 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14296 @section Count Words Recursively
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14297 @cindex Count words recursively
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14298 @cindex Recursively counting words
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14299 @cindex Words, counted recursively
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 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
14302 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
14303
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14304 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
14305 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
14306 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
14307 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
14308
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14309 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
14310 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
14311 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
14312 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
14313 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
14314 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
14315 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
14316
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14317 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
14318 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
14319
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14320 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
14321 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
14322 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
14323 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
14324
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14325 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14326 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
14327 previous versions:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14328
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14329 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14330 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14331 ;; @r{Recursive version; uses regular expression search}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14332 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14333 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14334 (@var{interactive-expression}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14335 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14336 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14337
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14338 ;;; @r{1. Set up appropriate conditions.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14339 (@var{explanatory message})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14340 (@var{set-up functions}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14341 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14342 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14343
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14344 ;;; @r{2. Count the words.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14345 @var{recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14346 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14347 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14348
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14349 ;;; @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
14350 @var{message providing word count}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14351 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14352 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14353
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14354 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
14355 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
14356 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
14357 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
14358 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
14359 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
14360 @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
14361 user.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14362
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14363 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
14364 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
14365 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
14366 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
14367
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14368 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14369 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
14370
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14371 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14372 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14373 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14374 "Print number of words in the region."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14375 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14376 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14377
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14378 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14379 ;;; @r{1. Set up appropriate conditions.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14380 (message "Counting words in region ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14381 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14382 (goto-char beginning)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14383 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14386 ;;; @r{2. Count the words.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14387 (let ((count (recursive-count-words end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14388 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14389
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14390 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14391 ;;; @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
14392 (cond ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14393 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14394 "The region does NOT have any words."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14395 ((= 1 count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14396 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14397 "The region has 1 word."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14398 (t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14399 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14400 "The region has %d words." count))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14401 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14402 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14403
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14404 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
14405
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14406 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
14407 `next-step-expression', and the recursive call.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14408
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14409 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
14410 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
14411 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
14412 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
14413 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
14414 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
14415 @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
14416 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
14417 argument.
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 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
14420 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
14421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14422 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
14423 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
14424 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
14425 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
14426 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
14427 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
14428
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14429 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
14430
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14431 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
14432 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
14433
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14434 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14435 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
14436
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14437 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14438 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14439 (defun recursive-count-words (region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14440 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14441 @var{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14442 @var{next-step-expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14443 @var{recursive call})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14444 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14445 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14446
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14447 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
14448 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
14449 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
14450 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
14451 function should return zero.
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 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
14454 succeeds, the function should call itself again.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14455
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14456 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14457 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
14458
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14459 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14460 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14461 (and (< (point) region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14462 (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
14463 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14464 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14465
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14466 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
14467 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
14468 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
14469 @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
14470 @code{re-search-forward} works.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14471
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14472 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
14473 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
14474 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
14475 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
14476 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
14477
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14478 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
14479 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
14480 part of the do-again-test.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14481
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14482 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
14483 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
14484 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
14485 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
14486 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
14487 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
14488
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14489 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14490 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
14491 function looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14492
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14493 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14494 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14495 (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
14496 ;; @r{then}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14497 @var{recursive-call-returning-count}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14498 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14499 @var{return-zero})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14500 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14501 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14502
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14503 How to incorporate the mechanism that counts?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14504
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14505 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
14506 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
14507 systematically.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14508
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14509 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
14510 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
14511 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
14512 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
14513 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
14514
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
14515 @need 800
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14516 Consider several cases:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14517
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14518 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14519 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14520 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
14521 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
14522 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
14523 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
14524
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14525 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14526 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
14527 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
14528 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
14529 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
14530
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14531 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14532 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
14533 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14534
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14535 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
14536 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
14537 @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
14538 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
14539
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14540 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14541 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
14542 adds one to its argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14543
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14544 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14545 (1+ (recursive-count-words region-end))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14546 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14547
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14548 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14549 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
14550 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14551
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14552 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14553 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14554 (defun recursive-count-words (region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14555 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14556
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14557 ;;; @r{1. do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14558 (if (and (< (point) region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14559 (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
14560 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14563 ;;; @r{2. then-part: the recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14564 (1+ (recursive-count-words region-end))
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 ;;; @r{3. else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14567 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14568 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14569 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14570
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14571 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14572 Let's examine how this works:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14573
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14574 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
14575 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
14576
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14577 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
14578 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
14579 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
14580 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
14581 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
14582 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
14583 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
14584
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14585 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
14586 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
14587 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
14588 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
14589 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
14590 @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
14591 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
14592 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
14593
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14594 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
14595 @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
14596 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
14597 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
14598 the correct amount.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14599
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14600 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
14601 @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
14602 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
14603 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
14604
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14605 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14606 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14607 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
14608
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14609 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14610 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14611 The recursive function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14612
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14613 @findex recursive-count-words
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14614 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14615 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14616 (defun recursive-count-words (region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14617 "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
14618 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14619
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14620 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14621 ;;; @r{1. do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14622 (if (and (< (point) region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14623 (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
14624 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14625
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14626 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14627 ;;; @r{2. then-part: the recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14628 (1+ (recursive-count-words region-end))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14629
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14630 ;;; @r{3. else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14631 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14632 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14633 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14634
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14635 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14636 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14637 The wrapper:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14638
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14639 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14640 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14641 ;;; @r{Recursive version}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14642 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14643 "Print number of words in the region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14644 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14645
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14646 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14647 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
14648 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
14649 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
14650 determines which characters these are."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14651 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14652 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14653 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14654 (message "Counting words in region ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14655 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14656 (goto-char beginning)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14657 (let ((count (recursive-count-words end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14658 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14659 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14660 (cond ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14661 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14662 "The region does NOT have any words."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14663 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14664 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14665 ((= 1 count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14666 (message "The region has 1 word."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14667 (t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14668 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14669 "The region has %d words." count))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14670 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14671 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14672
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14673 @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
14674 @section Exercise: Counting Punctuation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14675
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14676 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
14677 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
14678 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
14679
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14680 @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
14681 @chapter Counting Words in a @code{defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14682 @cindex Counting words in a @code{defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14683 @cindex Word counting in a @code{defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14684
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14685 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
14686 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
14687 @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
14688 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
14689 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
14690 @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
14691 @code{count-word-region}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14692
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14693 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
14694 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
14695 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
14696 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
14697 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
14698 and this will tell.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14699
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14700 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14701 * Divide and Conquer::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
14702 * Words and Symbols:: What to count?
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
14703 * Syntax:: What constitutes a word or symbol?
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
14704 * count-words-in-defun:: Very like @code{count-words}.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
14705 * Several defuns:: Counting several defuns in a file.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
14706 * Find a File:: Do you want to look at a file?
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
14707 * lengths-list-file:: A list of the lengths of many definitions.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
14708 * Several files:: Counting in definitions in different files.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
14709 * Several files recursively:: Recursively counting in different files.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
14710 * Prepare the data:: Prepare the data for display in a graph.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14711 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14712
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14713 @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
14714 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14715 @unnumberedsec Divide and Conquer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14716 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14717
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14718 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
14719 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
14720 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
14721 steps must be:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14722
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14723 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14724 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14725 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
14726 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
14727
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14728 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14729 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
14730 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
14731 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14732
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14733 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14734 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
14735 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
14736 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
14737 definitions within them.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14738
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14739 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14740 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
14741 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
14742 a graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14743
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14744 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14745 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
14746 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14747
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14748 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
14749 be difficult.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14750
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14751 @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
14752 @section What to Count?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14753 @cindex Words and symbols in defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14754
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14755 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
14756 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
14757 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
14758 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
14759 `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
14760 function contains the five symbols @code{defun},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14761 @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
14762 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
14763 @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
14764 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
14765 of ten words and symbols.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14766
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14767 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14768 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14769 (defun multiply-by-seven (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14770 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14771 (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14772 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14773 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14774
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14775 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14776 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
14777 @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
14778 @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
14779 @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
14780 ten! Something is wrong!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14781
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14782 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
14783 @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
14784 @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
14785 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
14786 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
14787 @samp{multiply by seven}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14788
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14789 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
14790 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
14791 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
14792 regexp is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14793
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14794 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14795 "\\w+\\W*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14796 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14797
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14798 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14799 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
14800 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
14801 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
14802 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
14803 of its own.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14804
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14805 @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
14806 @section What Constitutes a Word or Symbol?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14807 @cindex Syntax categories and tables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14808
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14809 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
14810 @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
14811 @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
14812 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
14813 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
14814 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
14815 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
14816 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
14817 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
14818 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
14819
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14820 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
14821 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
14822 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
14823 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
14824 @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
14825 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
14826 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
14827
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14828 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
14829 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
14830
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14831 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
14832 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
14833 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
14834 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
14835 constituent character; there are others, too.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14836
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14837 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
14838 @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
14839 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
14840
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14841 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14842 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
14843 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
14844
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14845 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14846 "\\(\\w\\|\\s_\\)+"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14847 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14850 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
14851 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
14852 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
14853 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
14854 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
14855 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
14856 characters must be matched at least once.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14857
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14858 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
14859 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
14860 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
14861 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
14862
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14863 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14864 "\\(\\W\\|\\S_\\)*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14865 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14868 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
14869 @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
14870 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
14871 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
14872
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14873 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
14874 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
14875 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
14876 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
14877 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
14878 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
14879 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
14880 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
14881 then followed optionally by white space.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14882
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14883 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14884 Here is the full regular expression:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14887 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14888 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14889
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14890 @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
14891 @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
14892 @cindex Counting words in a @code{defun}
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 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
14895 @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
14896 @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
14897 versions.
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 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
14900 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
14901 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
14902 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
14903 simplify the definition a little.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14904
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14905 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
14906 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
14907 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
14908 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
14909 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
14910 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
14911 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14912
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14913 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14914 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
14915
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14916 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14917 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14918 (defun count-words-in-defun ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14919 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14920 (@var{set up}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14921 (@var{while loop}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14922 @var{return count})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14923 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14924 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14925
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14926 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14927 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
14928
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14929 First, the set up.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14930
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14931 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
14932 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
14933 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
14934 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
14935 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
14936 end of the definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14937
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14938 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
14939 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
14940 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
14941 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
14942 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
14943 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
14944 place point where we wish to start.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14945
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14946 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
14947 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
14948 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
14949
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14950 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
14951 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
14952 @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
14953 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
14954
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14955 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
14956 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
14957 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
14958 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
14959 looping.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14960
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14961 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14962 The code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14963
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 (beginning-of-defun)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14967 (let ((count 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14968 (end (save-excursion (end-of-defun) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14969 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14970 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14971
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14972 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14973 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
14974 @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
14975 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
14976 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
14977 definition.
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 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
14980 is the @code{while} loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14981
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14982 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
14983 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
14984 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
14985 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
14986 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
14987 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
14988
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14989 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14990 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14991 (while (and (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14992 (re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14993 "\\(\\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
14994 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14995 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14996 @end smallexample
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 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
14999 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
15000 @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
15001 @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
15002
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15003 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15004 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
15005
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15006 @findex count-words-in-defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15007 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15008 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15009 (defun count-words-in-defun ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15010 "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
15011 (beginning-of-defun)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15012 (let ((count 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15013 (end (save-excursion (end-of-defun) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15014 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15015 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15016 (while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15017 (and (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15018 (re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15019 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15020 end t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15021 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15022 count))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15023 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15024 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15025
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15026 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
15027 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
15028 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
15029 @code{count-words-region}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15030
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15031 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15032 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15033 ;;; @r{Interactive version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15034 (defun count-words-defun ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15035 "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
15036 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15037 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15038 "Counting words and symbols in function definition ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15039 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15040 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15041 (let ((count (count-words-in-defun)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15042 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15043 ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15044 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15045 "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
15046 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15047 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15048 ((= 1 count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15049 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15050 "The definition has 1 word or symbol."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15051 (t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15052 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15053 "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
15054 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15055 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15056
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15057 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15058 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15059 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
15060
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15061 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15062 (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
15063 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15064
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15065 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
15066 @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
15067 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
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 (defun multiply-by-seven (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15072 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15073 (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15074 @result{} 10
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15075 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15076 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15077
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15078 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15079 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
15080
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15081 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
15082 several definitions within a single file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15083
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15084 @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
15085 @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
15086
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15087 A file such as @file{simple.el} may have a hundred or more function
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15088 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
15089 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
15090 statistics on one file.
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 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
15093 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
15094
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15095 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
15096 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
15097 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
15098 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
15099 messages.
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 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
15102 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
15103 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
15104 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
15105 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
15106
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15107 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
15108 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
15109 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
15110 (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
15111 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
15112 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
15113 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
15114 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
15115 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
15116 is almost all there is to it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15117
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15118 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15119 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
15120
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15121 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15122 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15123 (goto-char (point-min))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15124 (while (re-search-forward "^(defun" nil t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15125 (setq lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15126 (cons (count-words-in-defun) lengths-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15127 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15128 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15129
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15130 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
15131 contains the function definitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15132
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15133 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
15134 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
15135 @file{*scratch*} buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15136
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15137 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
15138
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15139 @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
15140 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15141 @section Find a File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15142 @cindex Find a File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15143
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15144 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
15145 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
15146 problem.
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 1200
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15149 Let's look at the source for @code{find-file}:
41421
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 find-file (filename)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15154 "Edit file FILENAME.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15155 Switch to a buffer visiting file FILENAME,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15156 creating one if none already exists."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15157 (interactive "FFind file: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15158 (switch-to-buffer (find-file-noselect filename)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15159 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15160 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15161
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15162 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15163 (The most recent version of the @code{find-file} function definition
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
15164 permits you to specify optional wildcards to visit multiple files; that
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15165 makes the definition more complex and we will not discuss it here,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15166 since it is not relevant. You can see its source using either
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15167 @kbd{M-.} (@code{find-tag}) or @kbd{C-h f} (@code{describe-function}).)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15168
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15169 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15170 In Emacs 22
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15171 (defun find-file (filename &optional wildcards)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15172 "Edit file FILENAME.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15173 Switch to a buffer visiting file FILENAME,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15174 creating one if none already exists.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15175 Interactively, the default if you just type RET is the current directory,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15176 but the visited file name is available through the minibuffer history:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15177 type M-n to pull it into the minibuffer.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15178
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15179 Interactively, or if WILDCARDS is non-nil in a call from Lisp,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15180 expand wildcards (if any) and visit multiple files. You can
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15181 suppress wildcard expansion by setting `find-file-wildcards' to nil.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15182
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15183 To visit a file without any kind of conversion and without
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15184 automatically choosing a major mode, use \\[find-file-literally]."
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15185 (interactive (find-file-read-args "Find file: " nil))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15186 (let ((value (find-file-noselect filename nil nil wildcards)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15187 (if (listp value)
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
15188 (mapcar 'switch-to-buffer (nreverse value))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15189 (switch-to-buffer value))))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15190 @end ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15191
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15192 The definition I am showing possesses short but complete documentation
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15193 and an interactive specification that prompts you for a file name when
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15194 you use the command interactively. The body of the definition
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15195 contains two functions, @code{find-file-noselect} and
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15196 @code{switch-to-buffer}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15197
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15198 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
15199 @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
15200 function reads the named file into a buffer and returns the buffer.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15201 (Its most recent version includes an optional wildcards argument,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15202 too, as well as another to read a file literally and an other you
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15203 suppress warning messages. These optional arguments are irrelevant.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15204
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15205 However, the @code{find-file-noselect} function does not select the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15206 buffer in which it puts the file. Emacs does not switch its attention
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
15207 (or yours if you are using @code{find-file-noselect}) to the selected
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15208 buffer. That is what @code{switch-to-buffer} does: it switches the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15209 buffer to which Emacs attention is directed; and it switches the
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15210 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
15211 buffer switching elsewhere. (@xref{Switching Buffers}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15212
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15213 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
15214 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
15215 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
15216 @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
15217 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
15218 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
15219 our own expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15220
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15221 The task is easy: use @code{find-file-noselect} and @code{set-buffer}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15222
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15223 @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
15224 @section @code{lengths-list-file} in Detail
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 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
15227 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
15228 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
15229 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
15230 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
15231 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
15232 @findex lengths-list-file
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15235 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15236 (defun lengths-list-file (filename)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15237 "Return list of definitions' lengths within FILE.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15238 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
15239 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
15240 symbols in one function definition."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15241 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15242 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15243 (message "Working on `%s' ... " filename)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15244 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15245 (let ((buffer (find-file-noselect filename))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15246 (lengths-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15247 (set-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15248 (setq buffer-read-only t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15249 (widen)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15250 (goto-char (point-min))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15251 (while (re-search-forward "^(defun" nil t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15252 (setq lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15253 (cons (count-words-in-defun) lengths-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15254 (kill-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15255 lengths-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15256 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15257 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15258
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15259 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15260 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
15261 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
15262 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
15263 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
15264 message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15265
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15266 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
15267 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
15268 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
15269 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
15270
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15271 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
15272 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
15273 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
15274 variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15275
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15276 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
15277
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15278 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
15279 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
15280 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
15281 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
15282 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
15283 caution. The reason for the caution is that this function and those
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
15284 it calls work on the sources for Emacs and it is inconvenient if they
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
15285 are inadvertently modified. It goes without saying that I did not
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
15286 realize a need for this line until an experiment went awry and started
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
15287 to modify my Emacs source files @dots{}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15288
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15289 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
15290 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
15291 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
15292 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
15293 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
15294 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
15295 won't.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15296
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15297 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
15298 beginning of the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15299
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15300 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
15301 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
15302 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
15303
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15304 Emacs kills the buffer after working through it. This is to save
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15305 space inside of Emacs. My version of GNU Emacs 19 contained over 300
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15306 source files of interest; GNU Emacs 22 contains over a thousand source
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15307 files. Another function will apply @code{lengths-list-file} to each
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15308 of the files.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15309
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15310 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
15311 @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
15312 the whole function.
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 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
15315 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
15316 C-e} (@code{eval-last-sexp}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15317
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
15318 @c !!! 22.1.1 lisp sources location here
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15319 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15320 (lengths-list-file
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
15321 "/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el")
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15322 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15323
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15324 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15325 (You may need to change the pathname of the file; the one here is for
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
15326 GNU Emacs version 22.1.1. To change the expression, copy it to
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15327 the @file{*scratch*} buffer and edit it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15328
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15329 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15330 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15331 (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
15332 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
15333
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15334 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15335 (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
15336 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15337
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15338 @noindent
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
15339 (@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
15340 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
15341
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15342 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15343 The lengths' list for @file{debug.el} takes less than a second to
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
15344 produce and looks like this in GNU Emacs 22:
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15345
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15346 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15347 (83 113 105 144 289 22 30 97 48 89 25 52 52 88 28 29 77 49 43 290 232 587)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15348 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15349
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15350 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15351 (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
15352 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
15353
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15354 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15355 (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
15356 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15357
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15358 (The newer version of @file{debug.el} contains more defuns than the
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15359 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
15360
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15361 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
15362 the list.
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 @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
15365 @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
15366
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15367 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
15368 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
15369 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
15370 a list of files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15371
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15372 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
15373 either a @code{while} loop or recursion.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15374
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15375 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
15376 * lengths-list-many-files:: Return a list of the lengths of defuns.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
15377 * append:: Attach one list to another.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15378 @end menu
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 @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
15381 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15382 @unnumberedsubsec Determine the lengths of @code{defuns}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15383 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15384
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15385 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
15386 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
15387 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
15388 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
15389 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
15390 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
15391 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
15392 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
15393 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
15394
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15395 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15396 The template looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15397
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15398 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15399 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15400 (while @var{test-whether-list-is-empty}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15401 @var{body}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15402 @var{set-list-to-cdr-of-list})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15403 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15404 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15405
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15406 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
15407 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
15408 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
15409 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
15410 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
15411 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
15412 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
15413 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
15414 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
15415 Example with an Incrementing Counter}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15416
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15417 @findex lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15418 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15419 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
15420
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15421 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15422 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15423 ;;; @r{Use @code{while} loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15424 (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
15425 "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
15426 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15427 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15428 (let (lengths-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15429
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15430 ;;; @r{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15431 (while list-of-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15432 (setq lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15433 (append
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15434 lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15435
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15436 ;;; @r{Generate a lengths' list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15437 (lengths-list-file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15438 (expand-file-name (car list-of-files)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15439 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15440
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15441 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15442 ;;; @r{Make files' list shorter.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15443 (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
15444
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15445 ;;; @r{Return final value of lengths' list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15446 lengths-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15447 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15448 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15449
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15450 @code{expand-file-name} is a built-in function that converts a file
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
15451 name to the absolute, long, path name form. The function employs the
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
15452 name of the directory in which the function is called.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15453
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
15454 @c !!! 22.1.1 lisp sources location here
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15455 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15456 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
15457 Emacs is visiting the
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
15458 @file{/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/} directory,
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15459
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15460 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15461 debug.el
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15462 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15463
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15464 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15465 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15466 becomes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15467
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
15468 @c !!! 22.1.1 lisp sources location here
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
15469 @smallexample
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
15470 /usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15471 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15472
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15473 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
15474 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
15475 itself.
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 @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
15478 @subsection The @code{append} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15479
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15480 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15481 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
15482
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15483 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15484 (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
15485 @end smallexample
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15488 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15489 produces the list
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 (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
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 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
15496 @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
15497 @code{cons},
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 (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
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15504 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15505 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
15506 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
15507
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15508 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15509 ((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
15510 @end smallexample
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 @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
15513 @section Recursively Count Words in Different Files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15514
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15515 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
15516 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
15517 is short and simple.
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 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
15520 `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
15521 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
15522 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
15523 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
15524 @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
15525 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
15526 function is shorter than this description!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15527 @findex recursive-lengths-list-many-files
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15530 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15531 (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
15532 "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
15533 (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
15534 (append
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15535 (lengths-list-file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15536 (expand-file-name (car list-of-files)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15537 (recursive-lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15538 (cdr list-of-files)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15539 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15540 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15541
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15542 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15543 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
15544 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
15545 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
15546
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15547 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
15548 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
15549 individually.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15550
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15551 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
15552 @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
15553 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
15554 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
15555 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
15556 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
15557
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15558 The results are shown after the @samp{@result{}}. (These results are
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
15559 for files from Emacs version 22.1.1; files from other versions of
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15560 Emacs may produce different results.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15561
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
15562 @c !!! 22.1.1 lisp sources location here
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
15563 @smallexample
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
15564 @group
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
15565 (cd "/usr/local/share/emacs/22.1.1/")
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15566
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15567 (lengths-list-file "./lisp/macros.el")
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15568 @result{} (283 263 480 90)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15569 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15570
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15571 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15572 (lengths-list-file "./lisp/mail/mailalias.el")
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15573 @result{} (38 32 29 95 178 180 321 218 324)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15574 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15575
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15576 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15577 (lengths-list-file "./lisp/makesum.el")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15578 @result{} (85 181)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15579 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15580
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15581 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15582 (recursive-lengths-list-many-files
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15583 '("./lisp/macros.el"
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15584 "./lisp/mail/mailalias.el"
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15585 "./lisp/makesum.el"))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15586 @result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 85 181)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15587 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15588 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15589
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15590 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
15591 output we want.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15592
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15593 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
15594
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15595 @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
15596 @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
15597
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15598 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
15599 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
15600 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
15601 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
15602 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
15603 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
15604 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
15605
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15606 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
15607 @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
15608 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
15609 numbers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15610
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
15611 @menu
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
15612 * Data for Display in Detail::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
15613 * Sorting:: Sorting lists.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
15614 * Files List:: Making a list of files.
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
15615 * Counting function definitions::
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
15616 @end menu
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
15617
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
15618 @node Data for Display in Detail, Sorting, Prepare the data, Prepare the data
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
15619 @ifnottex
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
15620 @unnumberedsubsec The Data for Display in Detail
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
15621 @end ifnottex
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
15622
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15623 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
15624 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
15625 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
15626 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
15627
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15628 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
15629 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
15630 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
15631 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
15632 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
15633 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
15634 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
15635 that we will need.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15636
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
15637 @node Sorting, Files List, Data for Display in Detail, Prepare the data
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15638 @subsection Sorting Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15639 @findex sort
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15640
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15641 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
15642 @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
15643 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
15644 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
15645
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15646 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
15647 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
15648 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
15649 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
15650 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
15651 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
15652 alphabetize a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15653
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15654 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15655 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
15656
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15657 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15658 (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
15659 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15660
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15661 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15662 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15663 produces this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15664
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15665 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15666 (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
15667 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15668
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15669 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15670 (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
15671 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
15672 arguments.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15673
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15674 Sorting the list returned by the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15675 @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
15676 it uses the @code{<} function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15677
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15678 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15679 2006 Oct 29
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15680 In GNU Emacs 22, eval
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15681 (progn
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15682 (cd "/usr/local/share/emacs/22.0.50/")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15683 (sort
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15684 (recursive-lengths-list-many-files
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15685 '("./lisp/macros.el"
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15686 "./lisp/mail/mailalias.el"
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15687 "./lisp/makesum.el"))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15688 '<))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15689
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15690 @end ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15691
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15692 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15693 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15694 (sort
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15695 (recursive-lengths-list-many-files
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15696 '("./lisp/macros.el"
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15697 "./lisp/mailalias.el"
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15698 "./lisp/makesum.el"))
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
15699 '<)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15700 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15701 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15702
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15703 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15704 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15705 which produces:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15706
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15707 @smallexample
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15708 (29 32 38 85 90 95 178 180 181 218 263 283 321 324 480)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15709 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15710
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15711 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15712 (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
15713 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
15714 list that is passed to @code{sort}.)
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 @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
15717 @subsection Making a List of Files
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 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
15720 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
15721 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
15722 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
15723 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
15724 recursive call.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15725
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15726 @findex directory-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15727 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
15728 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
15729 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
15730 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
15731 pattern within a single directory.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15732
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15733 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
15734 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
15735 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
15736 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
15737 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
15738 function that descends into the sub-directories.
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 @findex files-in-below-directory
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15741 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
15742 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
15743 @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
15744 @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
15745 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
15746 of sub-directories, but also their attributes.
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 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
15749 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
15750 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
15751
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15752 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15753 @group
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15754 ("./lisp/macros.el"
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15755 "./lisp/mail/rmail.el"
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15756 "./lisp/makesum.el")
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15757 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15758 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15759
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15760 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
15761 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
15762 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
15763 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
15764 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
15765 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
15766 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
15767
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15768 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
15769 is @file{abbrev.el}. Its name is
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
15770 @file{/usr/local/share/emacs/22.1.1/lisp/abbrev.el} and it is not a
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15771 directory or a symbolic link.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15772
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15773 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15774 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
15775 its attributes:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15776
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15777 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15778 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15779 ("abbrev.el"
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15780 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15781 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15782 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15783 100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15784 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15785 @group
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15786 (17733 259)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15787 (17491 28834)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15788 (17596 62124)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15789 13157
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15790 "-rw-rw-r--"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15791 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15792 @group
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15793 nil
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15794 2971624
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15795 773)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15796 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15797 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15798
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15799 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15800 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
15801 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
15802
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15803 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15804 @group
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15805 ("mail"
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15806 t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15807 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15808 )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15809 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15810 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15811
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15812 (To learn about the different attributes, look at the documentation of
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15813 @code{file-attributes}. Bear in mind that the @code{file-attributes}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15814 function does not list the filename, so its first element is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15815 @code{directory-files-and-attributes}'s second element.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15816
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15817 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
15818 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
15819 any directories below that directory.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15820
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15821 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
15822 @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
15823 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
15824 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
15825 sub-directory and repeat its actions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15826
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15827 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
15828 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
15829 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
15830 @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
15831 @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
15832 @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
15833 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
15834 directory.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15835
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15836 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
15837 several tasks:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15838
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15839 @itemize @bullet
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 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
15842 @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
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 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
15846 directory; and if so,
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 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15849 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15850 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
15851 so skip it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15852
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15853 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15854 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
15855 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15856 @end itemize
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 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
15859 @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
15860 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
15861 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
15862 pattern is `accumulate'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15863 (@pxref{Accumulate, , Recursive Pattern: @emph{accumulate}}),
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15864 using @code{append} as the combiner.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15865
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15866 @ignore
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15867 (directory-files "/usr/local/src/emacs/lisp/" t "\\.el$")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15868 (shell-command "find /usr/local/src/emacs/lisp/ -name '*.el'")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15869
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
15870 (directory-files "/usr/local/share/emacs/22.1.1/lisp/" t "\\.el$")
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
15871 (shell-command "find /usr/local/share/emacs/22.1.1/lisp/ -name '*.el'")
73680
a171b46b168c Replace 22.0.100 with 22.1.100.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73619
diff changeset
15872 @end ignore
a171b46b168c Replace 22.0.100 with 22.1.100.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73619
diff changeset
15873
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
15874 @c /usr/local/share/emacs/22.1.1/lisp/
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15875
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15876 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15877 Here is the function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15878
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15879 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15880 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15881 (defun files-in-below-directory (directory)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15882 "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
15883 ;; 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
15884 ;; 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
15885 ;; The directory will have a name such as
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
15886 ;; "/usr/local/share/emacs/22.1.1/lisp/"
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15887 (interactive "DDirectory name: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15888 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15889 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15890 (let (el-files-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15891 (current-directory-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15892 (directory-files-and-attributes directory t)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15893 ;; while we are in the current directory
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15894 (while current-directory-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15895 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15896 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15897 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15898 ;; 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
15899 ;; 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
15900 ((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
15901 (setq el-files-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15902 (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
15903 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15904 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15905 ;; 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
15906 ((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
15907 ;; decide whether to skip or recurse
57460
a60664800358 Remove trailing whitespace from file.
Robert J. Chassell <bob@rattlesnake.com>
parents: 57459
diff changeset
15908 (if
57459
dc60b5774fad (files-in-below-directory): remove unneeded `or' expression that looks
Robert J. Chassell <bob@rattlesnake.com>
parents: 57378
diff changeset
15909 (equal "."
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15910 (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
15911 ;; 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
15912 ;; current directory or parent, "." or ".."
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15913 ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15914 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15915 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15916 ;; 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
15917 (setq el-files-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15918 (append
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15919 (files-in-below-directory
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15920 (car (car current-directory-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15921 el-files-list)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15922 ;; 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
15923 ;; 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
15924 (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
15925 ;; return the filenames
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15926 el-files-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15927 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15928 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15929
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15930 @c (files-in-below-directory "/usr/local/src/emacs/lisp/")
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
15931 @c (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")
41421
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 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
15934 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
15935
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15936 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15937 Thus, on my system,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15938
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15939 @c (length (files-in-below-directory "/usr/local/src/emacs/lisp/"))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15940
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
15941 @c !!! 22.1.1 lisp sources location here
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15942 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15943 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15944 (length
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
15945 (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/"))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15946 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15947 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15948
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15949 @noindent
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
15950 tells me that in and below my Lisp sources directory are 1031
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
15951 @samp{.el} files.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15952
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15953 @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
15954 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
15955 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15956
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15957 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15958 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15959 (sort
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
15960 (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15961 'string-lessp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15962 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15963 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15964
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15965 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15966 (defun test ()
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15967 "Test how long it takes to find lengths of all sorted elisp defuns."
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15968 (insert "\n" (current-time-string) "\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15969 (sit-for 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15970 (sort
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15971 (recursive-lengths-list-many-files
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
15972 (files-in-below-directory "/usr/local/src/emacs/lisp/"))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15973 '<)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15974 (insert (format "%s" (current-time-string))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15975 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15976
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15977 @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
15978 @subsection Counting function definitions
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 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
15981 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
15982 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
15983 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
15984
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15985 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
15986 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
15987 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
15988 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
15989 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
15990 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
15991 numbers the @code{top-of-ranges} list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15992
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15993 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15994 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
15995 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
15996 @vindex top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15997
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15998 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15999 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16000 (defvar top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16001 '(10 20 30 40 50
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16002 60 70 80 90 100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16003 110 120 130 140 150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16004 160 170 180 190 200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16005 210 220 230 240 250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16006 260 270 280 290 300)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16007 "List specifying ranges for `defuns-per-range'.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16008 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16009 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16010
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16011 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
16012
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16013 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
16014 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
16015 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
16016 as arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16017
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16018 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
16019 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
16020 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
16021 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
16022 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
16023 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
16024 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
16025 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
16026 top-of-range values in turn.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16027
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16028 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
16029 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
16030 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
16031 small gear inside a big gear.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16032
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16033 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
16034 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
16035 (@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
16036 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
16037 @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
16038 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
16039 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
16040
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16041 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16042 The inner loop looks like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16045 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16046 (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
16047 (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
16048 (setq sorted-lengths (cdr sorted-lengths)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16049 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16050 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16051
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16052 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
16053 @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
16054 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
16055
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16056 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16057 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16058 (while top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16059 @var{body-of-loop}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16060 (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
16061 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16062 @end smallexample
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16065 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
16066
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16067 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16068 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16069 (while top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16070
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16071 ;; @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
16072 (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
16073 (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
16074 (setq sorted-lengths (cdr sorted-lengths)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16075
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16076 ;; @r{Move to next range.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16077 (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
16078 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16079 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16080
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16081 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
16082 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
16083 @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
16084 this purpose. (@xref{cons, , @code{cons}}.)
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 @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
16087 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
16088 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
16089 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
16090 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
16091 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
16092 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
16093 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
16094 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
16095 @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
16096 @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
16097 @findex nreverse
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16098
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16099 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16100 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16101
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16102 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16103 (nreverse '(1 2 3 4))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16104 @end smallexample
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16107 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16108 produces:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16109
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16110 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16111 (4 3 2 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16112 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16113
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16114 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
16115 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
16116 @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
16117 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
16118 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
16119 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
16120 as is.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16121 @findex reverse
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16122
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16123 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16124 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
16125
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16126 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16127 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16128 (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
16129 "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
16130 (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
16131 (number-within-range 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16132 defuns-per-range-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16133 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16134
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16135 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16136 ;; @r{Outer loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16137 (while top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16138 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16139
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16140 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16141 ;; @r{Inner loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16142 (while (and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16143 ;; @r{Need number for numeric test.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16144 (car sorted-lengths)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16145 (< (car sorted-lengths) top-of-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16146 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16147
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16148 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16149 ;; @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
16150 (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
16151 (setq sorted-lengths (cdr sorted-lengths)))
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 ;; @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
16154 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16157 (setq defuns-per-range-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16158 (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
16159 (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
16160 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16161
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16162 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16163 ;; @r{Move to next range.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16164 (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
16165 ;; @r{Specify next top of range value.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16166 (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
16167 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16168
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16169 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16170 ;; @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
16171 ;; @r{ the largest top-of-range value.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16172 (setq defuns-per-range-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16173 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16174 (length sorted-lengths)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16175 defuns-per-range-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16176 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16179 ;; @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
16180 ;; @r{ smallest to largest.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16181 (nreverse defuns-per-range-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16182 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16183 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16184
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16185 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16186 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16187 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
16188 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
16189
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16190 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16191 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16192 (and (car sorted-lengths)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16193 (< (car sorted-lengths) top-of-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16194 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16195 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16196
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16197 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16198 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16199 instead of like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16201 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16202 (< (car sorted-lengths) top-of-range)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16203 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16204
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16205 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
16206 @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
16207 range.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16208
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16209 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
16210 @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
16211 @code{(car sorted-lengths)} expression function returns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16212 @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
16213 @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
16214 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
16215
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16216 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
16217 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
16218 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
16219 the test will fail.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16220
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16221 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
16222 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
16223 @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
16224 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
16225 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
16226 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
16227 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
16228 @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
16229 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
16230 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
16231 of the @code{and} expression.
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 @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
16234 This way, we avoid an error.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16235 @iftex
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16236 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16237 (For information about @code{and}, see
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16238 @ref{kill-new function, , The @code{kill-new} function}.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16239 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16240 @ifinfo
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16241 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16242 (@xref{kill-new function, , The @code{kill-new} function}, for
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16243 information about @code{and}.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16244 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16245
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16246 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
16247 evaluate the expression that binds (a shortened)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16248 @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
16249 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
16250 evaluate the @code{defuns-per-range} function.
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16253 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16254 ;; @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
16255 (setq top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16256 '(110 120 130 140 150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16257 160 170 180 190 200))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16258
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16259 (setq sorted-lengths
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16260 '(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
16261
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16262 (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
16263 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16264 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16265
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16266 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16267 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16268 The list returned looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16269
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16270 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16271 (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
16272 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16273
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16274 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16275 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
16276 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
16277 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
16278 of 200 or larger.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16279
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16280 @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
16281 @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
16282 @chapter Readying a Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16283 @cindex Readying a graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16284 @cindex Graph prototype
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16285 @cindex Prototype graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16286 @cindex Body of graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16287
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16288 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
16289 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
16290
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16291 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
16292 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
16293 (@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
16294 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
16295 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
16296 more.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16297
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16298 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
16299 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
16300 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
16301 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
16302 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
16303 the function to label the axes automatically.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16304
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16305 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16306 * Columns of a graph::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
16307 * graph-body-print:: How to print the body of a graph.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16308 * recursive-graph-body-print::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16309 * Printed Axes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16310 * Line Graph Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16311 @end menu
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 @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
16314 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16315 @unnumberedsec Printing the Columns of a Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16316 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16317
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16318 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
16319 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
16320 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
16321 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
16322 symbol a user option.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16323
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16324 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
16325 @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
16326 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
16327
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16328 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
16329 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
16330 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
16331 @code{numbers-list}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16332
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16333 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
16334 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
16335
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16336 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
16337 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
16338 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
16339 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
16340
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16341 To see whether there is one in Emacs, we can use the @kbd{M-x apropos}
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16342 command. This command is like the @kbd{C-h a} (@code{command-apropos})
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16343 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
16344 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
16345 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
16346 @findex apropos
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16347
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16348 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
16349 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
16350 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
16351 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
16352 print\|insert\|column RET} and look at the result. On my system, this
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16353 command once too takes quite some time, and then produced a list of 79
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16354 functions and variables. Now it does not take much time at all and
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16355 produces a list of 211 functions and variables. Scanning down the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16356 list, the only function that looks as if it might do the job is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16357 @code{insert-rectangle}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16358
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16359 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16360 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
16361
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16362 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16363 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16364 insert-rectangle:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16365 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
16366 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
16367 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
16368 RECTANGLE should be a list of strings.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16369 After this command, the mark is at the upper left corner
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16370 and point is at the lower right corner.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16371 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16372 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16373
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16374 We 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
16375
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16376 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
16377 @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
16378 (@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
16379 @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
16380 point. Also the function returns @code{nil}.
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16383 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16384 (insert-rectangle '("first" "second" "third"))first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16385 second
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16386 thirdnil
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16387 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16388 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16389
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16390 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16391 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
16392 @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
16393 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
16394 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
16395 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
16396 column of strings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16397
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16398 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
16399 switching to another buffer, such as the @file{*scratch*} buffer,
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16400 placing point somewhere in the buffer, typing @kbd{M-:}, typing the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16401 @code{insert-rectangle} expression into the minibuffer at the prompt,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16402 and then typing @key{RET}. This causes Emacs to evaluate the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16403 expression in the minibuffer, but to use as the value of point the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16404 position of point in the @file{*scratch*} buffer. (@kbd{M-:} is the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16405 keybinding for @code{eval-expression}. Also, @code{nil} does not
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16406 appear in the @file{*scratch*} buffer since the expression is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16407 evaluated in the minibuffer.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16408
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16409 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
16410 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
16411 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
16412 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
16413 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
16414 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
16415
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16416 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
16417 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
16418 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
16419 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
16420 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
16421 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
16422 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
16423 right---or perhaps we can@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16424
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16425 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
16426 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
16427 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
16428 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
16429 @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
16430 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
16431 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
16432 be difficult.
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 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
16435 @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
16436 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
16437 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
16438 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
16439 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
16440 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
16441 @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
16442
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16443 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16444 (" " " " "*" "*" "*")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16445 @end smallexample
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 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
16448 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
16449 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
16450 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
16451 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
16452 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
16453 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
16454 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
16455 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
16456 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
16457 example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16458
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16459 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16460 (max 3 4 6 5 7 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16461 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16462
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16463 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16464 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
16465 smallest of all its arguments.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16466 @findex max
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16467 @findex min
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16468
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16469 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
16470 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
16471 numbers. Thus, the following expression,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16472
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16473 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16474 (max '(3 4 6 5 7 3))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16475 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16476
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16477 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16478 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16479 produces the following error message;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16480
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16481 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16482 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
16483 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16484
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16485 @findex apply
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16486 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
16487 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
16488 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
16489 may be a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16490
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16491 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16492 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16493
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16494 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16495 (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
16496 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16497
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16498 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16499 returns 8.
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 (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
16502 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
16503 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
16504 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
16505 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
16506 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
16507 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
16508 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
16509 it.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16510
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16511 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
16512 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
16513 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
16514
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16515 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16516 (apply 'max '(4 8 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16517 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16518
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16519 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
16520 @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
16521 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
16522 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
16523 sorted or not.)
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16526 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
16527
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16528 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16529 (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
16530 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16531
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16532 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
16533 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
16534 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
16535 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
16536 @code{insert-rectangle} command to insert.
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 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
16539 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
16540 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
16541 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
16542 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
16543 @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
16544
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16545 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16546 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16547 ;;; @r{First version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16548 (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
16549 "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
16550 (let ((insert-list nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16551 (number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16552 (- max-graph-height actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16553 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16554
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16555 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16556 ;; @r{Fill in asterisks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16557 (while (> actual-height 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16558 (setq insert-list (cons "*" insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16559 (setq actual-height (1- actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16560 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16561
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16562 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16563 ;; @r{Fill in blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16564 (while (> number-of-top-blanks 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16565 (setq insert-list (cons " " insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16566 (setq number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16567 (1- number-of-top-blanks)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16568 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16569
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16570 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16571 ;; @r{Return whole list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16572 insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16573 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16574 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16575
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16576 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
16577 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
16578
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16579 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16580 (column-of-graph 5 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16581 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16582
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16583 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16584 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16585 returns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16586
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16587 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16588 (" " " " "*" "*" "*")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16589 @end smallexample
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 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
16592 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
16593 `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
16594 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
16595 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
16596 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
16597 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
16598 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
16599 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
16600 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
16601 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
16602 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
16603 those variables separately.
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 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
16606 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
16607
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16608 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16609 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16610 (defvar graph-symbol "*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16611 "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
16612 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16613
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16614 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16615 (defvar graph-blank " "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16616 "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
16617 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
16618 as graph-symbol.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16619 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16620 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16621
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16622 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16623 (For an explanation of @code{defvar}, see
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16624 @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
16625
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16626 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16627 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16628 ;;; @r{Second version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16629 (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
16630 "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
16631
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16632 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16633 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16634 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
16635 of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16636 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
16637 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
16638 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16639
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16640 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16641 (let ((insert-list nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16642 (number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16643 (- max-graph-height actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16644 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16645
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16646 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16647 ;; @r{Fill in @code{graph-symbols}.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16648 (while (> actual-height 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16649 (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
16650 (setq actual-height (1- actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16651 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16652
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16653 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16654 ;; @r{Fill in @code{graph-blanks}.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16655 (while (> number-of-top-blanks 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16656 (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
16657 (setq number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16658 (1- number-of-top-blanks)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16659
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16660 ;; @r{Return whole list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16661 insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16662 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16663 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16664
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16665 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
16666 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
16667 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
16668 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
16669 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
16670 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
16671 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
16672 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
16673 the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16674
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16675 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
16676 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
16677 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
16678 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
16679 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
16680 simple.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16681
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16682 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
16683 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
16684 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
16685
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16686 @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
16687 @section The @code{graph-body-print} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16688 @findex graph-body-print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16690 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
16691 @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
16692 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
16693 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
16694 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
16695 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
16696 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
16697
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16698 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
16699 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
16700
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16701 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
16702 version of this function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16703
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16704 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16705 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16706 (defun graph-body-print (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16707 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16708 (let ((height @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16709 @dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16710 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16711
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16712 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16713 (while numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16714 @var{insert-columns-and-reposition-point}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16715 (setq numbers-list (cdr numbers-list)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16716 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16717 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16718
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16719 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16720 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
16721
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16722 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
16723 determine the height of the graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16724
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16725 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
16726 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
16727 (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
16728 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
16729
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16730 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
16731 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
16732 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
16733 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
16734 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
16735 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
16736 from which @code{insert-rectangle} is called.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16737
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16738 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
16739 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
16740 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
16741 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
16742 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
16743 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
16744 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
16745 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
16746 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
16747
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16748 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16749 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
16750
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16751 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16752 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16753 (defun graph-body-print (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16754 "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
16755 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
16756
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16757 (let ((height (apply 'max numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16758 (symbol-width (length graph-blank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16759 from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16760 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16761
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16762 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16763 (while numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16764 (setq from-position (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16765 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16766 (column-of-graph height (car numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16767 (goto-char from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16768 (forward-char symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16769 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16770 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16771 ;; @r{Draw graph column by column.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16772 (sit-for 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16773 (setq numbers-list (cdr numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16774 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16775 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16776 ;; @r{Place point for X axis labels.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16777 (forward-line height)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16778 (insert "\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16779 ))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16780 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16781 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16782
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16783 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16784 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
16785 @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
16786 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
16787 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
16788 `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
16789 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
16790 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
16791 function exits.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16792
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16793 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
16794
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16795 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16796 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16797 Install @code{graph-symbol}, @code{graph-blank},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16798 @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
16799 @iftex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
16800 @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
16801 @end iftex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
16802 @ifinfo
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
16803 @ref{Columns of a graph},
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
16804 @end ifinfo
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16805 and @code{graph-body-print}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16806
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16807 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16808 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16809 Copy the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16810
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16811 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16812 (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
16813 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16814
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16815 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16816 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
16817 want the graph to start.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16818
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16819 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16820 Type @kbd{M-:} (@code{eval-expression}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16821
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16822 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16823 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
16824 with @kbd{C-y} (@code{yank)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16825
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16826 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16827 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
16828 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16829
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16830 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16831 Emacs will print a graph like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16832
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16833 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16834 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16835 *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16836 * **
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16837 * ****
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16838 *** ****
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16839 ********* *
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 *************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16842 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16843 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16844
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16845 @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
16846 @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
16847 @findex recursive-graph-body-print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16848
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16849 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
16850 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
16851 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
16852 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
16853 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
16854 the graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16855
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16856 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16857 The `wrapper' is uncomplicated:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16858
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16859 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16860 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16861 (defun recursive-graph-body-print (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16862 "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
16863 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
16864 (let ((height (apply 'max numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16865 (symbol-width (length graph-blank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16866 from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16867 (recursive-graph-body-print-internal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16868 numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16869 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16870 symbol-width)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16871 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16872 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16873
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16874 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
16875 the `do-again-test', the printing code, the recursive call, and the
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
16876 `next-step-expression'. The `do-again-test' is a @code{when}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16877 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
16878 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
16879 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
16880 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
16881 `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
16882 version of the @code{numbers-list}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16883
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16884 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16885 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16886 (defun recursive-graph-body-print-internal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16887 (numbers-list height symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16888 "Print a bar graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16889 Used within recursive-graph-body-print function."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16890 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16891
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16892 @group
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
16893 (when numbers-list
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16894 (setq from-position (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16895 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16896 (column-of-graph height (car numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16897 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16898 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16899 (goto-char from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16900 (forward-char symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16901 (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
16902 (recursive-graph-body-print-internal
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
16903 (cdr numbers-list) height symbol-width)))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16904 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16905 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16906
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16907 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16908 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
16909
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16910 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16911 (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
16912 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16913
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16914 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16915 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
16916
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16917 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16918 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16919 *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16920 ** *
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 **** ***
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16923 * *********
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16924 ************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16925 *************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16926 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16927 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16928
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16929 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
16930 @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
16931
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16932 @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
16933 @section Need for Printed Axes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16934
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16935 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
16936 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
16937 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
16938
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16939 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
16940 @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
16941 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
16942 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
16943 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
16944
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16945 @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
16946 @section Exercise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16947
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16948 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
16949
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16950 @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
16951 @chapter Your @file{.emacs} File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16952 @cindex @file{.emacs} file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16953 @cindex Customizing your @file{.emacs} file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16954 @cindex Initialization file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16955
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16956 ``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
16957 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
16958 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
16959 it to suit themselves.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16960
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16961 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
16962 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
16963
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16964 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16965 * Default Configuration::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
16966 * Site-wide Init:: You can write site-wide init files.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
16967 * defcustom:: Emacs will write code for you.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
16968 * Beginning a .emacs File:: How to write a @code{.emacs file}.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
16969 * Text and Auto-fill:: Automatically wrap lines.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
16970 * Mail Aliases:: Use abbreviations for email addresses.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
16971 * Indent Tabs Mode:: Don't use tabs with @TeX{}
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
16972 * Keybindings:: Create some personal keybindings.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
16973 * Keymaps:: More about key binding.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
16974 * Loading Files:: Load (i.e., evaluate) files automatically.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
16975 * Autoload:: Make functions available.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
16976 * Simple Extension:: Define a function; bind it to a key.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
16977 * X11 Colors:: Colors in X.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16978 * Miscellaneous::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
16979 * Mode Line:: How to customize your mode line.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16980 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16981
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16982 @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
16983 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16984 @unnumberedsec Emacs' Default Configuration
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16985 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16986
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16987 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
16988 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
16989 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
16990 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
16991 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
16992 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
16993 right default for such a file, just as C mode is the right default for
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16994 editing C code. (Enough programming languages have syntaxes
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16995 that enable them to share or nearly share features, so C mode is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16996 now provided by by CC mode, the `C Collection'.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16997
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
16998 But when you do know who is going to use Emacs---you,
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16999 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
17000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17001 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
17002 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
17003 customize Emacs: so it suits me.
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 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
17006 @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
17007 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
17008 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
17009 @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
17010 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
17011 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
17012 naming conventions; the old format saves typing.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17013
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17014 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
17015 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
17016 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
17017 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
17018
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17019 (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
17020 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
17021 @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
17022
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17023 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
17024 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
17025 @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
17026 @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
17027 Manual}.
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 @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
17030 @section Site-wide Initialization Files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17031
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17032 @cindex @file{default.el} init file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17033 @cindex @file{site-init.el} init file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17034 @cindex @file{site-load.el} init file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17035 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
17036 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
17037 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
17038 everyone.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17039
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17040 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
17041 @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
17042 `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
17043 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
17044 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
17045 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
17046 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
17047 @file{INSTALL} file.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17048
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17049 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
17050 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
17051 @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
17052 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
17053 loaded @emph{after} your @file{.emacs} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17054
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17055 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
17056 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
17057 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
17058 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
17059 (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
17060 @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
17061 Simple Extension}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17062
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17063 @c Rewritten to avoid overfull hbox.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17064 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
17065 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
17066
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17067 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
17068 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
17069 Emacs distribution and are worth perusing.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17070
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17071 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
17072 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
17073 initialization file.
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 @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
17076 @section Specifying Variables using @code{defcustom}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17077 @findex defcustom
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17078
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17079 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
17080 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
17081 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
17082 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
17083 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
17084 file.)
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 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
17087 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
17088 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
17089 job.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17090
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17091 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
17092 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
17093 @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
17094 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
17095 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
17096 documentation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17097
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17098 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
17099 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
17100 arguments are optional.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17101
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17102 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
17103 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
17104
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17105 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17106 For example, the customizable user option variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17107 @code{text-mode-hook} looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17108
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17109 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17110 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17111 (defcustom text-mode-hook nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17112 "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
17113 :type 'hook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17114 :options '(turn-on-auto-fill flyspell-mode)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17115 :group 'data)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17116 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17117 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17118
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17119 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17120 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
17121 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
17122
53099
0d765aaa0e44 In node defvar and asterisk, following suggestions by Juri Linkov
Robert J. Chassell <bob@rattlesnake.com>
parents: 53086
diff changeset
17123 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
17124 @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
17125 Customization buffer.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17126
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17127 The @code{:options} keyword specifies a suggested list of values for
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17128 the variable. Usually, @code{:options} applies to a hook.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17129 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
17130 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
17131 @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
17132 user.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17133
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17134 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
17135 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
17136 find it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17137
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17138 The @code{defcustom} function recognizes more than a dozen keywords.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17139 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
17140 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
17141
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17142 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
17143
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17144 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
17145 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
17146
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17147 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17148 Using the customization command, you can type:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17149
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17150 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17151 M-x customize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17152 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17153
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17154 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17155 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
17156 Enter that group. Text Mode Hook is the first member. You can click
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17157 on its various options, such as @code{turn-on-auto-fill}, to set the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17158 values. After you click on the button to
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17159
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17160 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17161 Save for Future Sessions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17162 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17163
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17164 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17165 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
17166 It will look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17167
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17168 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17169 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17170 (custom-set-variables
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17171 ;; custom-set-variables was added by Custom.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17172 ;; If you edit it by hand, you could mess it up, so be careful.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17173 ;; Your init file should contain only one such instance.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17174 ;; If there is more than one, they won't work right.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17175 '(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
17176 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17177 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17178
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17179 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17180 (The @code{text-mode-hook-identify} function tells
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17181 @code{toggle-text-mode-auto-fill} which buffers are in Text mode.
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17182 It comes on automatically.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17183
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17184 The @code{custom-set-variables} function works somewhat differently
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17185 than a @code{setq}. While I have never learned the differences, I
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17186 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
17187 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
17188 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
17189 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
17190
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17191 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
17192 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
17193 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
17194 @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
17195 @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
17196
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17197 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
17198 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
17199 with the @code{custom-set-@dots{}} functions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17201 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17202 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
17203 message that says
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17204
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17205 @smallexample
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17206 CHANGED outside Customize; operating on it here may be unreliable.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17207 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17208
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17209 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17210 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
17211
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17212 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17213 Save for Future Sessions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17214 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17215
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17216 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17217 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
17218 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
17219 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
17220 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
17221 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
17222 forget, you may confuse yourself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17223
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17224 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
17225 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
17226 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
17227
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17228 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
17229 expressions myself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17230
73597
4d65d5858190 * emacs-lisp-intro.texi: Remove version reference for X colors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73587
diff changeset
17231 @findex defsubst
4d65d5858190 * emacs-lisp-intro.texi: Remove version reference for X colors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73587
diff changeset
17232 @findex defconst
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17233 Incidentally, to be more complete concerning defines: @code{defsubst}
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17234 defines an inline function. The syntax is just like that of
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17235 @code{defun}. @code{defconst} defines a symbol as a constant. The
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17236 intent is that neither programs nor users should ever change a value
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17237 set by @code{defconst}. (You can change it; the value set is a
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17238 variable; but please do not.)
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
17239
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17240 @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
17241 @section Beginning a @file{.emacs} File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17242 @cindex @file{.emacs} file, beginning of
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 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
17245 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
17246 @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
17247
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17248 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
17249 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
17250 definitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17251
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17252 @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
17253 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
17254
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17255 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
17256 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
17257
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17258 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
17259 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
17260 not.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17261
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
17262 @need 1200
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17263 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17264 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17265 ;;;; Bob's .emacs file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17266 ; Robert J. Chassell
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17267 ; 26 September 1985
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17268 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17269 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17270
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17271 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17272 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
17273 adding to it ever since.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17274
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17275 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17276 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17277 ; 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
17278 ; line beginning with four semicolons; and each
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17279 ; 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
17280 ; three semicolons.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17281 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17282 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17283
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17284 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17285 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
17286 Everything on a line that follows a semicolon is a comment. Two,
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17287 three, and four semicolons are used as subsection and section markers.
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17288 (@xref{Comments, ,, elisp, The GNU Emacs Lisp Reference Manual}, for
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17289 more about comments.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17290
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17291 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17292 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17293 ;;;; The Help Key
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17294 ; Control-h is the help key;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17295 ; 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
17296 ; 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
17297 ; For an explanation of the help facility,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17298 ; 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
17299 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17300 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17301
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17302 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17303 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
17304
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17305 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17306 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17307 ; 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
17308 ; 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
17309 ; 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
17310 ; control-h m.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17311 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17312 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17313
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17314 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17315 `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
17316 all you need to know.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17317
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17318 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
17319 @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
17320 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
17321 remember to look here to remind myself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17322
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17323 @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
17324 @section Text and Auto Fill Mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17325
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17326 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
17327 Auto Fill mode.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17328
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17329 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17330 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17331 ;;; Text mode and Auto Fill mode
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17332 ; The next two lines put Emacs into Text mode
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17333 ; 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
17334 ; 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
17335 (setq default-major-mode 'text-mode)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17336 (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
17337 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17338 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17339
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17340 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
17341 besides remind a forgetful human!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17342
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17343 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
17344 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
17345 other mode, such as C mode.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17346
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17347 @cindex Per-buffer, local variables list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17348 @cindex Local variables list, per-buffer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17349 @cindex Automatic mode selection
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17350 @cindex Mode selection, automatic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17351 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
17352 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
17353 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
17354 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
17355 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
17356 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
17357 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
17358 per-buffer, ``local variables list'', if any.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17359
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17360 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17361 @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
17362 Emacs Manual}.
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 @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
17365 Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17366 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17367 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17368 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
17369 Files'' in @cite{The GNU Emacs Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17370 @end iftex
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 Now, back to the @file{.emacs} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17373
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17374 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17375 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
17376
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17377 @cindex Text Mode turned on
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17378 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17379 (setq default-major-mode 'text-mode)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17380 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17381
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17382 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17383 This 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
17384
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17385 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
17386 @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
17387 @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
17388 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
17389 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
17390 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
17391 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
17392 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
17393 else in Emacs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17394
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17395 @need 800
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17396 Here is the next line:
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17397
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17398 @cindex Auto Fill mode turned on
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17399 @findex add-hook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17400 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17401 (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
17402 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17403
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17404 @noindent
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17405 In this line, the @code{add-hook} command adds
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17406 @code{turn-on-auto-fill} to the variable.
41421
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 @code{turn-on-auto-fill} is the name of a program, that, you guessed
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17409 it!, turns on Auto Fill mode.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17410
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17411 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
17412 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
17413 turns on Auto Fill mode.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17414
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17415 In brief, the first line causes Emacs to enter Text mode when you edit a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17416 file, unless the file name extension, a first non-blank line, or local
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17417 variables to tell Emacs otherwise.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17418
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17419 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
17420 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
17421 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
17422 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
17423 @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
17424 the @samp{t} of @samp{it's}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17425
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17426 The second line causes Emacs to turn on Auto Fill mode when it turns
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17427 on Text mode. In Auto Fill mode, Emacs automatically breaks a line
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17428 that is too wide and brings the excessively wide part of the line down
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17429 to the next line. Emacs breaks lines between words, not within them.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17430
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17431 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
17432 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
17433 @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
17434 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
17435 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
17436
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17437 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17438 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
17439 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
17440
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17441 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17442 (setq colon-double-space t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17443 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17444
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17445 @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
17446 @section Mail Aliases
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17447
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17448 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
17449 reminders.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17450
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 ;;; Mail mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17454 ; 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
17455 ; To enter RMAIL (for reading mail),
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17456 ; type `M-x rmail'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17457 (setq mail-aliases t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17458 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17459 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17460
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17461 @cindex Mail aliases
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17462 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17463 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
17464 @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
17465 says, in effect, ``Yes, use mail aliases.''
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17466
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17467 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
17468 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
17469 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
17470
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17471 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17472 alias geo george@@foobar.wiz.edu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17473 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17474
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17475 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17476 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
17477 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
17478
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17479 @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
17480 @section Indent Tabs Mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17481 @cindex Tabs, preventing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17482 @findex indent-tabs-mode
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 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
17485 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
17486 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
17487 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
17488 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
17489
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17490 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17491 The following turns off Indent Tabs mode:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17492
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17493 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17494 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17495 ;;; Prevent Extraneous Tabs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17496 (setq-default indent-tabs-mode nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17497 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17498 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17499
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17500 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
17501 @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
17502 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
17503 values for the variable.
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 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17506 @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
17507
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17508 @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
17509 Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17510 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17511 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17512 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
17513 Files'' in @cite{The GNU Emacs Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17514 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17515
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17516 @need 1700
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17517 @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
17518 @section Some Keybindings
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17519
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17520 Now for some personal keybindings:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17521
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17522 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17523 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17524 ;;; Compare windows
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17525 (global-set-key "\C-cw" 'compare-windows)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17526 @end group
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 @findex compare-windows
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17530 @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
17531 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
17532 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
17533 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
17534
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17535 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
17536
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17537 @cindex Setting a key globally
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17538 @cindex Global set key
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17539 @cindex Key setting globally
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17540 @findex global-set-key
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17541 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
17542 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
17543 shown: @code{\C-c} stands for `control-c', which means `press the
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17544 control key and the @key{c} key at the same time'. The @code{w} means
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17545 `press the @key{w} key'. The keybinding is surrounded by double
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17546 quotation marks. In documentation, you would write this as
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17547 @w{@kbd{C-c w}}. (If you were binding a @key{META} key, such as
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17548 @kbd{M-c}, rather than a @key{CTRL} key, you would write
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17549 @w{@code{\M-c}} in your @file{.emacs} file. @xref{Init Rebinding, ,
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17550 Rebinding Keys in Your Init File, emacs, The GNU Emacs Manual}, for
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17551 details.)
41421
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 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
17554 @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
17555 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
17556
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17557 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
17558 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
17559 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
17560 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
17561 adapt what is there.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17562
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17563 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
17564 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
17565 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
17566 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
17567 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
17568 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
17569 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
17570 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
17571 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
17572
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17573 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17574 Here is another keybinding, with a comment:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17575
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17576 @smallexample
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 ;;; Keybinding for `occur'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17579 ; 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
17580 (global-set-key "\C-co" 'occur)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17581 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17582 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17583
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17584 @findex occur
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17585 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
17586 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
17587 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
17588 to jump to occurrences.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17589
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17590 @findex global-unset-key
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17591 @cindex Unbinding key
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17592 @cindex Key unbinding
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17593 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17594 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
17595 work:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17596
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17597 @smallexample
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 ;;; Unbind `C-x f'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17600 (global-unset-key "\C-xf")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17601 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17602 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17603
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17604 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
17605 @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
17606 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
17607 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
17608 default width, I simply unbound the key.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17609
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17610 @findex list-buffers, @r{rebound}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17611 @findex buffer-menu, @r{bound to key}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17612 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17613 The following rebinds an existing key:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17614
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17615 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17616 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17617 ;;; 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
17618 (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
17619 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17620 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17621
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17622 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
17623 @code{list-buffers} command. This command lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17624 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
17625 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
17626 window, I prefer the @code{buffer-menu}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17627 command, which not only lists the buffers,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17628 but moves point into that window.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17629
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17630 @node Keymaps, Loading Files, Keybindings, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17631 @section Keymaps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17632 @cindex Keymaps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17633 @cindex Rebinding keys
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17634
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17635 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
17636 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
17637 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
17638 @code{current-global-map}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17639
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17640 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
17641 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
17642 all buffers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17643
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17644 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
17645 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
17646 function @code{buffer-menu}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17647
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17648 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17649 (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
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 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
17653 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
17654 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
17655 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
17656 to @kbd{C-c C-c g}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17657
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17658 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17659 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17660 (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
17661 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17662 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17663
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17664 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17665 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
17666 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
17667 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
17668 @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
17669 (@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
17670 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
17671 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
17672
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17673 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17674 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
17675
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17676 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17677 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17678 (defun texinfo-insert-@@group ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17679 "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
17680 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17681 (beginning-of-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17682 (insert "@@group\n"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17683 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17684 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17685
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17686 (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
17687 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
17688 with other Texinfo mode key bindings.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17690 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
17691 @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
17692 @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
17693
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17694 @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
17695 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
17696 Reference Manual}, for more information about keymaps.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17697
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17698 @node Loading Files, Autoload, Keymaps, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17699 @section Loading Files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17700 @cindex Loading files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17701 @c findex load
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17702
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17703 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
17704 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
17705 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
17706 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
17707
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17708 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
17709 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
17710 For example:
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 @c (auto-compression-mode t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17713
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17714 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17715 (load "~/emacs/slowsplit")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17716 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17717
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17718 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
17719 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
17720 @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
17721 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
17722 1989.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17723
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17724 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
17725 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
17726 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
17727 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
17728 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
17729 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
17730 window.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17731
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17732 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17733 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
17734 @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
17735 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
17736
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17737 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17738 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17739 (global-unset-key "\C-x2")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17740 (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
17741 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17742 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17743
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17744 @vindex load-path
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17745 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
17746 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
17747 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
17748 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
17749 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
17750 when Emacs is built.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17751
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17752 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17753 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
17754 existing load path:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17755
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17756 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17757 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17758 ;;; Emacs Load Path
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17759 (setq load-path (cons "~/emacs" load-path))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17760 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17761 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17762
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17763 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
17764 @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
17765
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17766 @findex load-library
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17767 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17768 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17769 (defun load-library (library)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17770 "Load the library named LIBRARY.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17771 This is an interface to the function `load'."
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17772 (interactive
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17773 (list (completing-read "Load library: "
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
17774 'locate-file-completion
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
17775 (cons load-path (get-load-suffixes)))))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17776 (load library))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17777 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17778 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17779
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17780 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
17781 `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
17782 @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
17783
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17784 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
17785 @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
17786 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
17787 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
17788
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17789 @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
17790 @section Autoloading
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17791 @findex autoload
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17792
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17793 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
17794 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
17795 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
17796 is called @dfn{autoloading}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17797
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17798 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
17799 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
17800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17801 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
17802 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
17803 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
17804
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17805 Rarely used functions are frequently autoloaded. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17806 @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
17807 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
17808 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
17809 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
17810 @file{.emacs} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17811
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
17812 In my @file{.emacs} file, I load 14 libraries that contain functions
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
17813 that would otherwise be autoloaded. (Actually, it would have been
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
17814 better to include these files in my `dumped' Emacs, but I forgot.
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
17815 @xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
17816 Reference Manual}, and the @file{INSTALL} file for more about
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
17817 dumping.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17818
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17819 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
17820 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
17821 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
17822 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
17823 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
17824 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
17825 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
17826 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
17827 function (the default is a function).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17828
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17829 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17830 Here is a typical example:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17833 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17834 (autoload 'html-helper-mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17835 "html-helper-mode" "Edit HTML documents" t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17836 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17837 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17838
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17839 @noindent
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17840 (@code{html-helper-mode} is an older alternative to @code{html-mode},
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17841 which is a standard part of the distribution.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17842
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17843 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17844 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
17845 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
17846 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
17847 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
17848 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
17849 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
17850 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
17851 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
17852 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
17853 documentation is not available.)
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 @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
17856 Manual}, for more information.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17857
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17858 @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
17859 @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
17860 @findex line-to-top-of-window
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17861 @cindex Simple extension in @file{.emacs} file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17862
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17863 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
17864 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
17865 to read.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17866
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17867 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
17868 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
17869 @file{.emacs} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17870
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17871 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17872 Here is the definition:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17873
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17874 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17875 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17876 ;;; Line to top of window;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17877 ;;; 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
17878 (defun line-to-top-of-window ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17879 "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
17880 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17881 (recenter 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17882 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17883 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17884
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17885 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17886 Now for the keybinding.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17887
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17888 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
17889 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
17890 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
17891 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
17892
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17893 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
17894 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17895
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17896 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17897 (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
17898 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17899
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17900 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
17901 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
17902
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17903 @cindex Conditional 'twixt two versions of Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17904 @cindex Version of Emacs, choosing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17905 @cindex Emacs version, choosing
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17906 If you run two versions of GNU Emacs, such as versions 21 and 22, and
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17907 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
17908 the following conditional:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17909
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17910 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17911 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17912 (cond
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17913 (= 21 emacs-major-version)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17914 ;; evaluate version 21 code
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17915 ( @dots{} ))
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17916 (= 22 emacs-major-version)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17917 ;; evaluate version 22 code
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17918 ( @dots{} )))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17919 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17920 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17921
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17922 For example, in contrast to version 20, more recent versions blink
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17923 their cursors by default. I hate such blinking, as well as other
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17924 features, so I placed the following in my @file{.emacs}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17925 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
17926 @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
17927
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17928 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17929 emacs -q --no-site-file -eval '(blink-cursor-mode nil)'
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17930
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17931 @exdent Or nowadays, using an even more sophisticated set of options,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17932
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
17933 emacs -Q - D
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17934 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17935 }:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17936
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17937 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17938 @group
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17939 (when (or (= 21 emacs-major-version)
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17940 (= 22 emacs-major-version))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17941 (blink-cursor-mode 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17942 ;; 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
17943 ;; at the end of the buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17944 (setq next-line-add-newlines t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17945 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17946 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17947 ;; Turn on image viewing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17948 (auto-image-file-mode t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17949 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17950 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17951 ;; 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
17952 ;; (Use numeric argument to turn on)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17953 (menu-bar-mode 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17954 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17955 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17956 ;; 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
17957 ;; (Use numeric argument to turn on)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17958 (tool-bar-mode nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17959 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17960 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17961 ;; Turn off tooltip mode for tool bar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17962 ;; (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
17963 ;; (Use numeric argument to turn on)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17964 (tooltip-mode nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17965 ;; If tooltips turned on, make tips appear promptly
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17966 (setq tooltip-delay 0.1) ; default is 0.7 second
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17967 )
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17968 @end group
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
17969 @end smallexample
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17970
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
17971 @need 1250
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
17972 Alternatively, since @code{blink-cursor-mode} has existed since Emacs
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
17973 version 21 and is likely to continue, you could write
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
17974
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
17975 @smallexample
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
17976 @group
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
17977 (when (>= emacs-major-version 21)
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
17978 (blink-cursor-mode 0)
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
17979 @end group
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
17980 @end smallexample
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
17981
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
17982 @noindent
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
17983 and add other expressions, too.
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
17984
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
17985
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17986 @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
17987 @section X11 Colors
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17988
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17989 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
17990 system.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17991
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17992 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
17993
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17994 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17995 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
17996 file that set values:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17997
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17998 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17999 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18000 ;; Set cursor color
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18001 (set-cursor-color "white")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18002
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18003 ;; Set mouse color
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18004 (set-mouse-color "white")
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 ;; Set foreground and background
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18007 (set-foreground-color "white")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18008 (set-background-color "darkblue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18009 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18010
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18011 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18012 ;;; Set highlighting colors for isearch and drag
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18013 (set-face-foreground 'highlight "white")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18014 (set-face-background 'highlight "blue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18015 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18016
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18017 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18018 (set-face-foreground 'region "cyan")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18019 (set-face-background 'region "blue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18020 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18021
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18022 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18023 (set-face-foreground 'secondary-selection "skyblue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18024 (set-face-background 'secondary-selection "darkblue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18025 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18026
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18027 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18028 ;; Set calendar highlighting colors
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18029 (setq calendar-load-hook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18030 '(lambda ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18031 (set-face-foreground 'diary-face "skyblue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18032 (set-face-background 'holiday-face "slate blue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18033 (set-face-foreground 'holiday-face "white")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18034 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18035 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18036
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18037 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
18038 the screen flicker.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18039
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18040 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
18041 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
18042 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
18043 @file{~/.Xresources} file like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18044
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18045 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18046 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18047 Emacs*foreground: white
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18048 Emacs*background: darkblue
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18049 Emacs*cursorColor: white
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18050 Emacs*pointerColor: white
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18051 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18052 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18053
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18054 In any event, since it is not part of Emacs, I set the root color of
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18055 my X window in my @file{~/.xinitrc} file, like this@footnote{I also
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18056 run more modern window managers, such as Enlightenment, Gnome, or KDE;
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18057 in those cases, I often specify an image rather than a plain color.}:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18058
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18059 @smallexample
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18060 xsetroot -solid Navy -fg white &
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
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
18063 @need 1700
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18064 @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
18065 @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
18066
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
18067 @need 1250
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18068 Here are a few miscellaneous settings:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18069 @sp 1
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 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18072 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18073 Set the shape and color of the mouse cursor:
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18074
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18075 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18076 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18077 ; Cursor shapes are defined in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18078 ; `/usr/include/X11/cursorfont.h';
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18079 ; 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
18080 ; 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
18081 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18082
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18083 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18084 (let ((mpointer (x-get-resource "*mpointer"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18085 "*emacs*mpointer")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18086 ;; 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
18087 ;; then set it, otherwise leave as is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18088 (if (eq mpointer nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18089 (setq mpointer "132")) ; top_left_arrow
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18090 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18091 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18092 (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
18093 (set-mouse-color "white"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18094 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18095 @end smallexample
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18096
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18097 @item
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18098 Or you can set the values of a variety of features in an alist, like
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18099 this:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18100
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18101 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18102 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18103 (setq-default
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18104 default-frame-alist
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18105 '((cursor-color . "white")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18106 (mouse-color . "white")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18107 (foreground-color . "white")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18108 (background-color . "DodgerBlue4")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18109 ;; (cursor-type . bar)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18110 (cursor-type . box)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18111 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18112 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18113 (tool-bar-lines . 0)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18114 (menu-bar-lines . 1)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18115 (width . 80)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18116 (height . 58)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18117 (font .
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18118 "-Misc-Fixed-Medium-R-Normal--20-200-75-75-C-100-ISO8859-1")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18119 ))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18120 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18121 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18122
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18123 @item
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
18124 Convert @kbd{@key{CTRL}-h} into @key{DEL} and @key{DEL}
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
18125 into @kbd{@key{CTRL}-h}.@*
70609
bd74271e8d03 Fix spelling errors.
Eli Zaretskii <eliz@gnu.org>
parents: 68640
diff changeset
18126 (Some older keyboards needed this, although I have not seen the
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18127 problem recently.)
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18128
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18129 @smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18130 @group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18131 ;; 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
18132 ; (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
18133
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18134 ;; 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
18135 (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
18136 @end group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18137 @end smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18138
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18139 @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
18140
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18141 @smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18142 @group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18143 (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
18144 (blink-cursor-mode -1))
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18145 @end group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18146 @end smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18147
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18148 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18149 or start GNU Emacs with the command @code{emacs -nbc}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18150
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
18151 @need 1250
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
18152 @item When using `grep'@*
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
18153 @samp{-i}@w{ } Ignore case distinctions@*
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18154 @samp{-n}@w{ } Prefix each line of output with line number@*
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
18155 @samp{-H}@w{ } Print the filename for each match.@*
57460
a60664800358 Remove trailing whitespace from file.
Robert J. Chassell <bob@rattlesnake.com>
parents: 57459
diff changeset
18156 @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
18157
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18158 @smallexample
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
18159 (setq grep-command "grep -i -nH -e ")
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18160 @end smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18161
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18162 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18163 @c Evidently, no longer needed in GNU Emacs 22
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18164
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18165 item Automatically uncompress compressed files when visiting them
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18166
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18167 smallexample
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18168 (load "uncompress")
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18169 end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18170
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18171 @end ignore
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18172
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18173 @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
18174 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
18175
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18176 @smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18177 (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
18178 @end smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18179
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18180 @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
18181
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18182 @smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18183 @group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18184 (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
18185 ;; 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
18186 ;; 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
18187 (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
18188 @end group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18189 @end smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18190
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18191 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
18192
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18193 @smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18194 @group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18195 (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
18196 (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
18197 @end group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18198 @end smallexample
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18199 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18200
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18201 @subsubheading Fixing Unpleasant Key Bindings
57460
a60664800358 Remove trailing whitespace from file.
Robert J. Chassell <bob@rattlesnake.com>
parents: 57459
diff changeset
18202 @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
18203 @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
18204
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18205 Some systems bind keys unpleasantly. Sometimes, for example, the
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
18206 @key{CTRL} key appears in an awkward spot rather than at the far left
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18207 of the home row.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18208
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18209 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
18210 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
18211 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
18212 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
18213 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
18214
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18215 @need 1250
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18216 @noindent
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18217 For a boot script:
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18218
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18219 @smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18220 @group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18221 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
18222 @exdent or
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18223 install-keymap emacs2
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18224 @end group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18225 @end smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18226
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18227 @need 1250
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18228 @noindent
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18229 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
18230 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
18231
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18232 @smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18233 @group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18234 # 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
18235 # (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
18236 # 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
18237
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18238 xmodmap -e "clear Lock"
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18239 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
18240 @end group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18241 @end smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18242
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18243 @need 1250
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18244 @noindent
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18245 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
18246 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
18247
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18248 @smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18249 @group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18250 # 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
18251 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
18252 @end group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18253 @end smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18254
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
18255 @need 1700
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18256 @node Mode Line, , Miscellaneous, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18257 @section A Modified Mode Line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18258 @vindex default-mode-line-format
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18259 @cindex Mode line format
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18260
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18261 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
18262
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18263 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
18264 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
18265
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18266 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
18267
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18268 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18269 -:-- 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
18270 @end smallexample
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 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
18273 @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
18274 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
18275
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18276 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18277 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
18278
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18279 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18280 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18281 ;; 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
18282 ;; 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
18283 (setq default-mode-line-format
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18284 (quote
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18285 (#("-" 0 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18286 (help-echo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18287 "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
18288 mode-line-mule-info
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18289 mode-line-modified
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18290 mode-line-frame-identification
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 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18293 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18294 mode-line-buffer-identification
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 (:eval (substring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18297 (system-name) 0 (string-match "\\..+" (system-name))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18298 ":"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18299 default-directory
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18300 #(" " 0 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18301 (help-echo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18302 "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
18303 (line-number-mode " Line %l ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18304 global-mode-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18305 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18306 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18307 #(" %[(" 0 6
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18308 (help-echo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18309 "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
18310 (:eval (mode-line-mode-name))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18311 mode-line-process
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18312 minor-mode-alist
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18313 #("%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
18314 ")%] "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18315 (-3 . "%P")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18316 ;; "-%-"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18317 )))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18318 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18319 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18320
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18321 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18322 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
18323 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
18324 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
18325 it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18326
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18327 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
18328 @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
18329 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
18330 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
18331 have not discussed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18332
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18333 @cindex Properties, in mode line example
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18334 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
18335 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
18336 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
18337 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
18338 over the hyphen, some help information appears (By default, you must
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18339 wait seven-tenths of a second before the information appears. You can
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18340 change that timing by changing the value of @code{tooltip-delay}.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18341
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18342 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18343 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
18344
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18345 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18346 #("-" 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
18347 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18348
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18349 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18350 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
18351 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
18352 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
18353 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
18354 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
18355 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
18356 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
18357 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
18358 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
18359 string format can be repeated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18360
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18361 @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
18362 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
18363 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
18364
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18365 @code{mode-line-buffer-identification}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18366 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
18367 beginning @code{(#("%12b" 0 4 @dots{}}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18368 The @code{#(} begins the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18369
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18370 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
18371 @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
18372 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
18373 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
18374 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
18375 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
18376 window.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18377
73597
4d65d5858190 * emacs-lisp-intro.texi: Remove version reference for X colors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73587
diff changeset
18378 @code{:eval} says to evaluate the following form and use the result as
4d65d5858190 * emacs-lisp-intro.texi: Remove version reference for X colors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73587
diff changeset
18379 a string to display. In this case, the expression displays the first
4d65d5858190 * emacs-lisp-intro.texi: Remove version reference for X colors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73587
diff changeset
18380 component of the full system name. The end of the first component is
4d65d5858190 * emacs-lisp-intro.texi: Remove version reference for X colors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73587
diff changeset
18381 a @samp{.} (`period'), so I use the @code{string-match} function to
4d65d5858190 * emacs-lisp-intro.texi: Remove version reference for X colors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73587
diff changeset
18382 tell me the length of the first component. The substring from the
4d65d5858190 * emacs-lisp-intro.texi: Remove version reference for X colors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73587
diff changeset
18383 zeroth character to that length is the name of the machine.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18384
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18385 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18386 This is the expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18387
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18388 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18389 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18390 (:eval (substring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18391 (system-name) 0 (string-match "\\..+" (system-name))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18392 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18393 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18394
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18395 @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
18396 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
18397 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
18398 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
18399 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
18400 @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
18401 out the line.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18402
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18403 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
18404 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
18405 keys than a default Emacs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18406
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18407 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
18408 Emacs, with no customization, type:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18409
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18410 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18411 emacs -q
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18412 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18413
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18414 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18415 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
18416 @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
18417 more.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18418
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18419 @node Debugging, Conclusion, Emacs Initialization, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18420 @chapter Debugging
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18421 @cindex debugging
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18422
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18423 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
18424 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
18425 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
18426
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18427 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
18428 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
18429 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
18430
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18431 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
18432 * debug:: How to use the built-in debugger.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
18433 * debug-on-entry:: Start debugging when you call a function.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
18434 * debug-on-quit:: Start debugging when you quit with @kbd{C-g}.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
18435 * edebug:: How to use Edebug, a source level debugger.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18436 * Debugging Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18437 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18438
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18439 @node debug, debug-on-entry, Debugging, Debugging
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18440 @section @code{debug}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18441 @findex debug
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18442
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18443 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
18444 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
18445 @code{triangle} function discussed earlier. @xref{Decrementing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18446 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
18447 @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
18448
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18449 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
18450 @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
18451
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18452 @findex triangle-bugged
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18453 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18454 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18455 (defun triangle-bugged (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18456 "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
18457 (let ((total 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18458 (while (> number 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18459 (setq total (+ total number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18460 (setq number (1= number))) ; @r{Error here.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18461 total))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18462 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18463 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18464
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18465 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
18466 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
18467 echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18468
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18469 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18470 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
18471 argument of 4:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18472
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18473 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18474 (triangle-bugged 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18475 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18476
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18477 @noindent
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
18478 In a recent GNU Emacs, you will create and enter a @file{*Backtrace*}
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
18479 buffer that says:
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18480
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18481 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18482 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18483 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18484 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18485 Debugger entered--Lisp error: (void-function 1=)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18486 (1= number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18487 (setq number (1= number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18488 (while (> number 0) (setq total (+ total number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18489 (setq number (1= number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18490 (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
18491 (setq number ...)) total)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18492 triangle-bugged(4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18493 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18494 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18495 eval((triangle-bugged 4))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18496 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18497 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18498 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18499 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18500 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18501 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18502
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18503 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18504 (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
18505 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
18506 the @file{*Backtrace*} buffer.)
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 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
18509 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
18510 function @code{1=} is `void'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18511
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18512 @ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18513 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18514 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
18515
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18516 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18517 Symbol's function definition is void:@: 1=
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18518 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18519
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18520 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18521 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
18522 version 21.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18523 @end ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18524
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18525 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
18526 You can read the complete backtrace.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18527
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
18528 In this case, you need to run a recent GNU Emacs, which automatically
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
18529 starts the debugger that puts you in the @file{*Backtrace*} buffer; or
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
18530 else, you need to start the debugger manually as described below.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18531
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18532 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
18533 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
18534 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
18535 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
18536 what the Lisp interpreter evaluated next.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18539 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
18540
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18541 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18542 (setq number (1= number))
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18546 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
18547 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
18548 top:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18549
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18550 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18551 (1= number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18552 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18553
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18554 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18555 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18556 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
18557
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18558 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18559 Debugger entered--Lisp error: (void-function 1=)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18560 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18561
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18562 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18563 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
18564 then run your test again.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18565
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18566 @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
18567 @section @code{debug-on-entry}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18568 @findex debug-on-entry
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18569
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
18570 A recent GNU Emacs starts the debugger automatically when your
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
18571 function has an error.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18572
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18573 @ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18574 GNU Emacs version 20 and before did not; it simply
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18575 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
18576 manually.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18577 @end ignore
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18578
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
18579 Incidentally, you can start the debugger manually for all versions of
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18580 Emacs; the advantage is that the debugger runs even if you do not have
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18581 a bug in your code. Sometimes your code will be free of bugs!
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18582
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18583 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
18584 @code{debug-on-entry}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18585
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18586 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18587 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18588 Type:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18589
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18590 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18591 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
18592 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18593
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18594 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18595 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18596 Now, evaluate the following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18597
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18598 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18599 (triangle-bugged 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18600 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18601
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18602 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18603 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
18604 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
18605 function:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18608 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18609 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18610 Debugger entered--entering a function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18611 * triangle-bugged(5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18612 eval((triangle-bugged 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18613 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18614 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18615 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18616 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18617 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18618 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18619 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18620 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18621
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18622 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
18623 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
18624 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18625
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18626 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18627 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18628 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18629 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
18630 * (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
18631 (setq number ...)) total)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18632 * triangle-bugged(5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18633 eval((triangle-bugged 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18634 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18635 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18636 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18637 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18638 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18639 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18640 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18641 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18642
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18643 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18644 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
18645 @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
18646 definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18647
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18648 @need 1750
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18649 Eventually, the buffer will look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18650
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18651 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18652 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18653 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18654 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
18655 * (setq number (1= number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18656 * (while (> number 0) (setq total (+ total number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18657 (setq number (1= number)))
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 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18660 * (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
18661 (setq number ...)) total)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18662 * triangle-bugged(5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18663 eval((triangle-bugged 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18664 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18665 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18666 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18667 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18668 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18669 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18670 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18671 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18672
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18673 @need 1500
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18674 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18675 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
18676 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
18677 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18678
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18679 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18680 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18681 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18682 Debugger entered--Lisp error: (void-function 1=)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18683 * (1= number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18684 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18685 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18686 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18687 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18688
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18689 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
18690
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18691 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
18692 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
18693
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18694 @findex cancel-debug-on-entry
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18695 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
18696 @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
18697
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18698 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18699 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
18700 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18701
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18702 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18703 (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
18704
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18705 @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
18706 @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
18707
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18708 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
18709 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
18710
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18711 @findex debug-on-quit
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18712 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
18713 (@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
18714 @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
18715
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18716 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18717 @cindex @code{(debug)} in code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18718 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
18719 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
18720
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18721 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18722 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18723 (defun triangle-bugged (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18724 "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
18725 (let ((total 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18726 (while (> number 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18727 (setq total (+ total number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18728 (debug) ; @r{Start debugger.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18729 (setq number (1= number))) ; @r{Error here.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18730 total))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18731 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18732 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18733
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18734 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
18735 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
18736
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18737 @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
18738 @section The @code{edebug} Source Level Debugger
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18739 @cindex Source level debugger
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18740 @findex edebug
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18741
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18742 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
18743 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
18744 shows which line you are currently executing.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18745
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18746 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
18747 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
18748
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18749 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
18750 Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18751
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
18752 @need 1250
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18753 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
18754 @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
18755 for a review of it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18756
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18757 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18758 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18759 (defun triangle-recursively-bugged (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18760 "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
18761 Uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18762 (if (= number 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18763 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18764 (+ number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18765 (triangle-recursively-bugged
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18766 (1= number))))) ; @r{Error here.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18767 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18768 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18771 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
18772 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
18773 (@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
18774 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
18775 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
18776 Interactive mode.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18777
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18778 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18779 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
18780 first @dfn{instrument} the code using a different command. You can do
73720
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
18781 this by positioning your cursor within or just after the definition
365d2ceb2a2e Yet more minor changes:
Robert J. Chassell <bob@rattlesnake.com>
parents: 73708
diff changeset
18782 and typing
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18783
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18784 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18785 M-x edebug-defun RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18786 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18787
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18788 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18789 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
18790 already loaded, and properly instrument the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18791
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18792 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
18793 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
18794
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18795 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18796 (triangle-recursively-bugged 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18797 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18798
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18799 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18800 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
18801 @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
18802 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
18803 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
18804 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
18805 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
18806 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
18807
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18808 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18809 =>@point{}(if (= number 1)
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18813 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18814 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
18815 @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
18816 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18817 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18818 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
18819 (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
18820 @end ifnottex
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 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
18823 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
18824
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18825 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18826 =>(if @point{}(= number 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18827 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18828
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18829 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18830 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
18831 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
18832 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
18833 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
18834
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18835 @smallexample
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18836 Result: 3 (#o3, #x3, ?\C-c)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18837 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18838
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18839 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18840 This means the value of @code{number} is 3, which is octal three,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18841 hexadecimal three, and @sc{ascii} `control-c' (the third letter of the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18842 alphabet, in case you need to know this information).
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18843
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18844 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
18845 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
18846
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18847 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18848 => @point{}(1= number))))) ; @r{Error here.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18849 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18850
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18851 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18852 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18853 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
18854 that says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18855
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18856 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18857 Symbol's function definition is void:@: 1=
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18858 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18859
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18860 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18861 This is the bug.
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 Press @kbd{q} to quit Edebug.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18864
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18865 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
18866 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
18867 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
18868 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
18869
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18870 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
18871 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
18872 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
18873 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
18874 times a function is called, and more.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18875
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18876 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
18877 Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18878
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18879 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18880 @node Debugging Exercises, , edebug, Debugging
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18881 @section Debugging Exercises
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18882
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18883 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18884 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18885 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
18886 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
18887 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
18888 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
18889 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
18890 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
18891 Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18892
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18893 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18894 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
18895 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
18896 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
18897 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
18898 completes without problems.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18899
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18900 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18901 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
18902 (The @code{global-edebug-prefix} is usually @kbd{C-x X}, i.e.@:
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
18903 @kbd{@key{CTRL}-x} followed by an upper case @kbd{X}; use this prefix
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18904 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
18905
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18906 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18907 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
18908 (@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
18909 @code{count-words-region} is working.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18910
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18911 @item
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18912 Move point to some spot further down the function and then type the
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18913 @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
18914
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18915 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18916 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
18917 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
18918 @code{edebug-Trace-fast-mode}.
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 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
18922 stopping point.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18923 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18924
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18925 @node Conclusion, the-the, Debugging, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18926 @chapter Conclusion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18927
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18928 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
18929 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
18930 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
18931 simple customizations and extensions to Emacs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18932
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18933 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
18934 teach yourself.
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 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
18937 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
18938 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
18939
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18940 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
18941 and in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18942 @ifnotinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18943 @cite{The GNU Emacs Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18944 @end ifnotinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18945 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18946 @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
18947 Emacs Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18948 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18949
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18950 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
18951 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
18952 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
18953
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18954 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
18955 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
18956 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
18957 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
18958 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
18959 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
18960
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18961 Go to the other on-line help that is part of GNU Emacs: the on-line
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18962 documentation for all functions and variables, and @code{find-tags},
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18963 the program that takes you to sources.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18964
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18965 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
18966 @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
18967 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
18968 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
18969 function, for example, looks complicated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18970
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18971 You may want to walk through this function slowly, as we did with the
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18972 @code{forward-sentence} function. (@xref{forward-sentence, The
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18973 @code{forward-sentence} function}.) Or you may want to skip that
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18974 function and look at another, such as @code{split-line}. You don't
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18975 need to read all the functions. According to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18976 @code{count-words-in-defun}, the @code{split-line} function contains
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18977 102 words and symbols.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18978
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18979 Even though it is short, @code{split-line} contains expressions
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18980 we have not studied: @code{skip-chars-forward}, @code{indent-to},
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
18981 @code{current-column} and @code{insert-and-inherit}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18982
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18983 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
18984 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
18985 @ref{Review, , Review}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18986
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18987 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
18988 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
18989 function. This gives you the function documentation.
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 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
18992 @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
18993 @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
18994 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
18995 @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
18996
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18997 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
18998 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
18999 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
19000 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
19001 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
19002 (@code{find-tag}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19003
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19004 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
19005 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
19006 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
19007
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19008 (The @code{indent-to} function is written in C rather than Emacs Lisp;
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19009 it is a `built-in' function. @code{help-follow} takes you to its
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19010 source as does @code{find-tag}, when properly set up.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19011
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19012 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
19013 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
19014 Manual has to say by visiting the manual in Info, and typing @kbd{i}
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19015 (@code{Info-index}) and the name of the function, or by looking up the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19016 function in the index to a printed copy of the manual.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19017
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19018 Similarly, you can find out what is meant by
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19019 @code{insert-and-inherit}.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19020
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19021 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
19022 @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
19023 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
19024 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
19025 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
19026 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
19027 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
19028 (@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
19029 Reference Manual}, for more about building.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19030
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19031 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
19032 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
19033 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
19034 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
19035 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
19036 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
19037 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
19038
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19039 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
19040 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
19041 beginning.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19042
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19043 @c ================ Appendix ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19044
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19045 @node the-the, Kill Ring, Conclusion, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19046 @appendix The @code{the-the} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19047 @findex the-the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19048 @cindex Duplicated words function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19049 @cindex Words, duplicated
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 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
19052 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
19053 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
19054 detecting duplicated words, @code{the-the}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19055
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19056 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19057 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
19058 search for duplicates:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19059
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19060 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19061 \\(\\w+[ \t\n]+\\)\\1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19062 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19063
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19064 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19065 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
19066 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
19067 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
19068 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
19069 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
19070 @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
19071 @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
19072 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
19073 The GNU Emacs Lisp Reference Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19074
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19075 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
19076 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
19077 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
19078
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19079 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
19080 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
19081 @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
19082 @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
19083
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19084 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19085 \\(\\(\\w+\\)\\W*\\)\\1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19086 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19087
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19088 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19089 Again, not useful.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19090
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19091 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
19092 @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
19093 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
19094 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
19095
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19096 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19097 \\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19098 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19099
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19100 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
19101 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
19102
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19103 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
19104 @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
19105
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19106 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19107 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19108 (defun the-the ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19109 "Search forward for for a duplicated word."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19110 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19111 (message "Searching for for duplicated words ...")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19112 (push-mark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19113 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19114 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19115 ;; This regexp is not perfect
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19116 ;; but is fairly good over all:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19117 (if (re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19118 "\\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
19119 (message "Found duplicated word.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19120 (message "End of buffer")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19121 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19124 ;; Bind `the-the' to C-c \
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19125 (global-set-key "\C-c\\" 'the-the)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19126 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19127 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19128
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19129 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19130 Here is test text:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19131
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19132 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19133 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19134 one two two three four five
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19135 five six seven
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19136 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19137 @end smallexample
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 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
19140 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
19141
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19142 @node Kill Ring, Full Graph, the-the, Top
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19143 @appendix Handling the Kill Ring
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19144 @cindex Kill ring handling
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19145 @cindex Handling the kill ring
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19146 @cindex Ring, making a list like a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19147
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19148 The kill ring is a list that is transformed into a ring by the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19149 workings of the @code{current-kill} function. The @code{yank} and
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19150 @code{yank-pop} commands use the @code{current-kill} function.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19151
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19152 This appendix describes the @code{current-kill} function as well as
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19153 both the @code{yank} and the @code{yank-pop} commands, but first,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19154 consider the workings of the kill ring.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19155
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19156 @menu
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19157 * What the Kill Ring Does::
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19158 * current-kill::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
19159 * yank:: Paste a copy of a clipped element.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
19160 * yank-pop:: Insert element pointed to.
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19161 * ring file::
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19162 @end menu
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19163
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19164 @node What the Kill Ring Does, current-kill, Kill Ring, Kill Ring
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19165 @ifnottex
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19166 @unnumberedsec What the Kill Ring Does
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19167 @end ifnottex
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19168
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19169 @need 1250
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19170 The kill ring has a default maximum length of sixty items; this number
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19171 is too large for an explanation. Instead, set it to four. Please
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19172 evaluate the following:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19173
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19174 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19175 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19176 (setq old-kill-ring-max kill-ring-max)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19177 (setq kill-ring-max 4)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19178 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19179 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19180
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19181 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19182 Then, please copy each line of the following indented example into the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19183 kill ring. You may kill each line with @kbd{C-k} or mark it and copy
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19184 it with @kbd{M-w}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19185
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19186 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19187 (In a read-only buffer, such as the @file{*info*} buffer, the kill
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19188 command, @kbd{C-k} (@code{kill-line}), will not remove the text,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19189 merely copy it to the kill ring. However, your machine may beep at
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19190 you. Alternatively, for silence, you may copy the region of each line
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19191 with the @kbd{M-w} (@code{kill-ring-save}) command. You must mark
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19192 each line for this command to succeed, but it does not matter at which
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19193 end you put point or mark.)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19194
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19195 @need 1250
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19196 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19197 Please invoke the calls in order, so that five elements attempt to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19198 fill the kill ring:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19199
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19200 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19201 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19202 first some text
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19203 second piece of text
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19204 third line
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19205 fourth line of text
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19206 fifth bit of text
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19207 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19208 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19209
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19210 @need 1250
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19211 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19212 Then find the value of @code{kill-ring} by evaluating
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19213
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19214 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19215 kill-ring
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19216 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19217
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19218 @need 800
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19219 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19220 It is:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19221
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19222 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19223 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19224 ("fifth bit of text" "fourth line of text"
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19225 "third line" "second piece of text")
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19226 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19227 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19228
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19229 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19230 The first element, @samp{first some text}, was dropped.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19231
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19232 @need 1250
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19233 To return to the old value for the length of the kill ring, evaluate:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19234
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19235 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19236 (setq kill-ring-max old-kill-ring-max)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19237 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19238
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19239 @node current-kill, yank, What the Kill Ring Does, Kill Ring
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19240 @comment node-name, next, previous, up
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19241 @appendixsec The @code{current-kill} Function
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19242 @findex current-kill
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19243
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19244 The @code{current-kill} function changes the element in the kill ring
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19245 to which @code{kill-ring-yank-pointer} points. (Also, the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19246 @code{kill-new} function sets @code{kill-ring-yank-pointer} to point
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19247 to the latest element of the the kill ring. The @code{kill-new}
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19248 function is used directly or indirectly by @code{kill-append},
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19249 @code{copy-region-as-kill}, @code{kill-ring-save}, @code{kill-line},
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19250 and @code{kill-region}.)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19251
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19252 @menu
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19253 * Code for current-kill::
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19254 * Understanding current-kill::
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19255 @end menu
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19256
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19257 @node Code for current-kill, Understanding current-kill, current-kill, current-kill
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19258 @ifnottex
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19259 @unnumberedsubsec The code for @code{current-kill}
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19260 @end ifnottex
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19261
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19262
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19263 @need 1500
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19264 The @code{current-kill} function is used by @code{yank} and by
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19265 @code{yank-pop}. Here is the code for @code{current-kill}:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19266
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19267 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19268 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19269 (defun current-kill (n &optional do-not-move)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19270 "Rotate the yanking point by N places, and then return that kill.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19271 If N is zero, `interprogram-paste-function' is set, and calling it
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19272 returns a string, then that string is added to the front of the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19273 kill ring and returned as the latest kill.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19274 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19275 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19276 If optional arg DO-NOT-MOVE is non-nil, then don't actually move the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19277 yanking point; just return the Nth kill forward."
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19278 (let ((interprogram-paste (and (= n 0)
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19279 interprogram-paste-function
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19280 (funcall interprogram-paste-function))))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19281 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19282 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19283 (if interprogram-paste
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19284 (progn
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19285 ;; Disable the interprogram cut function when we add the new
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19286 ;; text to the kill ring, so Emacs doesn't try to own the
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19287 ;; selection, with identical text.
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19288 (let ((interprogram-cut-function nil))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19289 (kill-new interprogram-paste))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19290 interprogram-paste)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19291 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19292 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19293 (or kill-ring (error "Kill ring is empty"))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19294 (let ((ARGth-kill-element
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19295 (nthcdr (mod (- n (length kill-ring-yank-pointer))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19296 (length kill-ring))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19297 kill-ring)))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19298 (or do-not-move
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19299 (setq kill-ring-yank-pointer ARGth-kill-element))
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19300 (car ARGth-kill-element)))))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19301 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19302 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19303
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19304 Remember also that the @code{kill-new} function sets
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19305 @code{kill-ring-yank-pointer} to the latest element of the the kill
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19306 ring, which means that all the functions that call it set the value
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19307 indirectly: @code{kill-append}, @code{copy-region-as-kill},
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19308 @code{kill-ring-save}, @code{kill-line}, and @code{kill-region}.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19309
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19310 @need 1500
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19311 Here is the line in @code{kill-new}, which is explained in
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19312 @ref{kill-new function, , The @code{kill-new} function}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19313
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19314 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19315 (setq kill-ring-yank-pointer kill-ring)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19316 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19317
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19318 @node Understanding current-kill, , Code for current-kill, current-kill
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19319 @ifnottex
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19320 @unnumberedsubsec @code{current-kill} in Outline
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19321 @end ifnottex
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19322
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19323 The @code{current-kill} function looks complex, but as usual, it can
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19324 be understood by taking it apart piece by piece. First look at it in
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19325 skeletal form:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19326
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19327 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19328 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19329 (defun current-kill (n &optional do-not-move)
73610
242f2b7c7873 Fix unbalanced quotes.
Juri Linkov <juri@jurta.org>
parents: 73609
diff changeset
19330 "Rotate the yanking point by N places, and then return that kill."
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19331 (let @var{varlist}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19332 @var{body}@dots{})
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 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19335
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19336 This function takes two arguments, one of which is optional. It has a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19337 documentation string. It is @emph{not} interactive.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19338
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19339 @menu
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19340 * Body of current-kill::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
19341 * Digression concerning error:: How to mislead humans, but not computers.
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19342 * Determining the Element::
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19343 @end menu
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19344
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19345 @node Body of current-kill, Digression concerning error, Understanding current-kill, Understanding current-kill
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19346 @ifnottex
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19347 @unnumberedsubsubsec The Body of @code{current-kill}
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19348 @end ifnottex
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19349
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19350 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
19351 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
19352
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19353 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
19354 within the bounds of this function. This variable is called
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19355 @code{interprogram-paste} and is for copying to another program. It
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19356 is not for copying within this instance of GNU Emacs. Most window
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19357 systems provide a facility for interprogram pasting. Sadly, that
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19358 facility usually provides only for the last element. Most windowing
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
19359 systems have not adopted a ring of many possibilities, even though
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19360 Emacs has provided it for decades.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19361
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19362 The @code{if} expression has two parts, one if there exists
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19363 @code{interprogram-paste} and one if not.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19364
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19365 @need 2000
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19366 Let us consider the `if not' or else-part of the @code{current-kill}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19367 function. (The then-part uses the the @code{kill-new} function, which
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19368 we have already described. @xref{kill-new function, , The
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19369 @code{kill-new} function}.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19370
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19371 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19372 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19373 (or kill-ring (error "Kill ring is empty"))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19374 (let ((ARGth-kill-element
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19375 (nthcdr (mod (- n (length kill-ring-yank-pointer))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19376 (length kill-ring))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19377 kill-ring)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19378 (or do-not-move
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19379 (setq kill-ring-yank-pointer ARGth-kill-element))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19380 (car ARGth-kill-element))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19381 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19382 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19383
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19384 @noindent
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19385 The code first checks whether the kill ring has content; otherwise it
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19386 signals an error.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19387
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19388 @need 1000
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19389 Note that the @code{or} expression is very similar to testing length
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19390 with an @code{if}:
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19391
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19392 @findex zerop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19393 @findex error
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19394 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19395 @group
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19396 (if (zerop (length kill-ring)) ; @r{if-part}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19397 (error "Kill ring is empty")) ; @r{then-part}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19398 ;; No else-part
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19399 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19400 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19401
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19402 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19403 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
19404 an error message sent to the user: @samp{Kill ring is empty}. The
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19405 @code{current-kill} function uses an @code{or} expression which is
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19406 simpler. But an @code{if} expression reminds us what goes on.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19407
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19408 This @code{if} expression uses the function @code{zerop} which returns
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19409 true if the value it is testing is zero. When @code{zerop} tests
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19410 true, the then-part of the @code{if} is evaluated. The then-part is a
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19411 list starting with the function @code{error}, which is a function that
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19412 is similar to the @code{message} function
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19413 (@pxref{message, , The @code{message} Function}) in that
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19414 it prints a one-line message in the echo area. However, in addition
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19415 to printing a message, @code{error} also stops evaluation of the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19416 function within which it is embedded. This means that the rest of the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19417 function will not be evaluated if the length of the kill ring is zero.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19418
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19419 Then the @code{current-kill} function selects the element to return.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19420 The selection depends on the number of places that @code{current-kill}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19421 rotates and on where @code{kill-ring-yank-pointer} points.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19422
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19423 Next, either the optional @code{do-not-move} argument is true or the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19424 current value of @code{kill-ring-yank-pointer} is set to point to the
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19425 list. Finally, another expression returns the first element of the
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19426 list even if the @code{do-not-move} argument is true.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19427
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19428 @node Digression concerning error, Determining the Element, Body of current-kill, Understanding current-kill
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19429 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19430 @unnumberedsubsubsec Digression about the word `error'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19431 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19432
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19433 In my opinion, it is slightly misleading, at least to humans, to use
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19434 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
19435 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
19436 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
19437 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
19438 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
19439 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
19440 exploration.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19441
70725
47db6078325c (Digression concerning error): Fix typo.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 70609
diff changeset
19442 From the human point of view, the act of exploration and discovery is
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19443 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
19444 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
19445 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
19446 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
19447 takes the same steps as it does when there is an `error', a term such as
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19448 `cancel' would have a clearer connotation.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19449
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19450 @node Determining the Element, , Digression concerning error, Understanding current-kill
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19451 @ifnottex
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19452 @unnumberedsubsubsec Determining the Element
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19453 @end ifnottex
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19454
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19455 Among other actions, the else-part of the @code{if} expression sets
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19456 the value of @code{kill-ring-yank-pointer} to
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19457 @code{ARGth-kill-element} when the kill ring has something in it and
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19458 the value of @code{do-not-move} is @code{nil}.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19459
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19460 @need 800
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19461 The code looks like this:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19462
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19463 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19464 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19465 (nthcdr (mod (- n (length kill-ring-yank-pointer))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19466 (length kill-ring))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19467 kill-ring)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19468 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19469 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19470
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19471 This needs some examination. Unless it is not supposed to move the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19472 pointer, the @code{current-kill} function changes where
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19473 @code{kill-ring-yank-pointer} points.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19474 That is what the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19475 @w{@code{(setq kill-ring-yank-pointer ARGth-kill-element))}}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19476 expression does. Also, clearly, @code{ARGth-kill-element} is being
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19477 set to be equal to some @sc{cdr} of the kill ring, using the
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19478 @code{nthcdr} function that is described in an earlier section.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19479 (@xref{copy-region-as-kill}.) How does it do this?
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19480
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19481 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
19482 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
19483 @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
19484
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19485 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19486 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
19487
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19488 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19489 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19490 (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
19491
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19492 (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
19493 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19494 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19495
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19496 However, the @code{nthcdr} expression is more complicated. It uses
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19497 the @code{mod} function to determine which @sc{cdr} to select.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19498
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19499 (You will remember to look at inner functions first; indeed, we will
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19500 have to go inside the @code{mod}.)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19501
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19502 The @code{mod} function returns the value of its first argument modulo
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19503 the second; that is to say, it returns the remainder after dividing
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19504 the first argument by the second. The value returned has the same
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19505 sign as the second argument.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19506
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19507 @need 800
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19508 Thus,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19509
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19510 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19511 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19512 (mod 12 4)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19513 @result{} 0 ;; @r{because there is no remainder}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19514 (mod 13 4)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19515 @result{} 1
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19516 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19517 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19518
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19519 @need 1250
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19520 In this case, the first argument is often smaller than the second.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19521 That is fine.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19522
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19523 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19524 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19525 (mod 0 4)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19526 @result{} 0
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19527 (mod 1 4)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19528 @result{} 1
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19529 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19530 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19531
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19532 We can guess what the @code{-} function does. It is like @code{+} but
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
19533 subtracts instead of adds; the @code{-} function subtracts its second
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19534 argument from its first. Also, we already know what the @code{length}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19535 function does (@pxref{length}). It returns the length of a list.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19536
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19537 And @code{n} is the name of the required argument to the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19538 @code{current-kill} function.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19539
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19540 @need 1250
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19541 So when the first argument to @code{nthcdr} is zero, the @code{nthcdr}
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19542 expression returns the whole list, as you can see by evaluating the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19543 following:
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19544
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19545 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19546 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19547 ;; kill-ring-yank-pointer @r{and} kill-ring @r{have a length of four}
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19548 ;; @r{and} (mod (- 0 4) 4) @result{} 0
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19549 (nthcdr (mod (- 0 4) 4)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19550 '("fourth line of text"
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19551 "third line"
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19552 "second piece of text"
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19553 "first some text"))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19554 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19555 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19556
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19557 @need 1250
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19558 When the first argument to the @code{current-kill} function is one,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19559 the @code{nthcdr} expression returns the list without its first
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19560 element.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19561
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19562 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19563 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19564 (nthcdr (mod (- 1 4) 4)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19565 '("fourth line of text"
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19566 "third line"
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19567 "second piece of text"
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19568 "first some text"))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19569 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19570 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19571
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19572 @cindex @samp{global variable} defined
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19573 @cindex @samp{variable, global}, defined
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
19574 Incidentally, both @code{kill-ring} and @code{kill-ring-yank-pointer}
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19575 are @dfn{global variables}. That means that any expression in Emacs
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19576 Lisp can access them. They are not like the local variables set by
73597
4d65d5858190 * emacs-lisp-intro.texi: Remove version reference for X colors.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73587
diff changeset
19577 @code{let} or like the symbols in an argument list.
73587
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
19578 Local variables can only be accessed
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
19579 within the @code{let} that defines them or the function that specifies
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
19580 them in an argument list (and within expressions called by them).
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
19581
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
19582 @ignore
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
19583 @c texi2dvi fails when the name of the section is within ifnottex ...
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
19584 (@xref{Prevent confusion, , @code{let} Prevents Confusion}, and
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
19585 @ref{defun, , The @code{defun} Special Form}.)
c84b73607df3 Removed INSTALL MANIFEST since those files are now irrelevant.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73554
diff changeset
19586 @end ignore
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19587
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19588 @node yank, yank-pop, current-kill, Kill Ring
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19589 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19590 @appendixsec @code{yank}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19591 @findex yank
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19592
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19593 After learning about @code{current-kill}, the code for the
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19594 @code{yank} function is almost easy.
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19595
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19596 The @code{yank} function does not use the
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19597 @code{kill-ring-yank-pointer} variable directly. It calls
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19598 @code{insert-for-yank} which calls @code{current-kill} which sets the
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19599 @code{kill-ring-yank-pointer} variable.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19600
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19601 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19602 The code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19603
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19604 @c in GNU Emacs 22
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19605 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19606 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19607 (defun yank (&optional arg)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19608 "Reinsert (\"paste\") the last stretch of killed text.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19609 More precisely, reinsert the stretch of killed text most recently
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19610 killed OR yanked. Put point at end, and set mark at beginning.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19611 With just \\[universal-argument] as argument, same but put point at
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19612 beginning (and mark at end). With argument N, reinsert the Nth most
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19613 recently killed stretch of killed text.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19614
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19615 When this command inserts killed text into the buffer, it honors
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19616 `yank-excluded-properties' and `yank-handler' as described in the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19617 doc string for `insert-for-yank-1', which see.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19618
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19619 See also the command \\[yank-pop]."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19620 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19621 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19622 (interactive "*P")
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19623 (setq yank-window-start (window-start))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19624 ;; If we don't get all the way thru, make last-command indicate that
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19625 ;; for the following command.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19626 (setq this-command t)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19627 (push-mark (point))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19628 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19629 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19630 (insert-for-yank (current-kill (cond
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19631 ((listp arg) 0)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19632 ((eq arg '-) -2)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19633 (t (1- arg)))))
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19634 (if (consp arg)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19635 ;; This is like exchange-point-and-mark,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19636 ;; but doesn't activate the mark.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19637 ;; It is cleaner to avoid activation, even though the command
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19638 ;; loop would deactivate the mark because we inserted text.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19639 (goto-char (prog1 (mark t)
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19640 (set-marker (mark-marker) (point) (current-buffer)))))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19641 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19642 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19643 ;; If we do get all the way thru, make this-command indicate that.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19644 (if (eq this-command t)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19645 (setq this-command 'yank))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19646 nil)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19647 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19648 @end smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19649
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19650 The key expression is @code{insert-for-yank}, which inserts the string
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19651 returned by @code{current-kill}, but removes some text properties from
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19652 it.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19653
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19654 However, before getting to that expression, the function sets the value
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19655 of @code{yank-window-start} to the position returned by the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19656 @code{(window-start)} expression, the position at which the display
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19657 currently starts. The @code{yank} function also sets
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19658 @code{this-command} and pushes the mark.
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19659
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19660 After it yanks the appropriate element, if the optional argument is a
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19661 @sc{cons} rather than a number or nothing, it puts point at beginning
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19662 of the yanked text and mark at its end.
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19663
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19664 (The @code{prog1} function is like @code{progn} but returns the value
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19665 of its first argument rather than the value of its last argument. Its
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19666 first argument is forced to return the buffer's mark as an integer.
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19667 You can see the documentation for these functions by placing point
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19668 over them in this buffer and then typing @kbd{C-h f}
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19669 (@code{describe-function}) followed by a @kbd{RET}; the default is the
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19670 function.)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19671
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19672 The last part of the function tells what to do when it succeeds.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19673
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
19674 @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
19675 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19676 @appendixsec @code{yank-pop}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19677 @findex yank-pop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19678
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19679 After understanding @code{yank} and @code{current-kill}, you know how
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19680 to approach the @code{yank-pop} function. Leaving out the
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19681 documentation to save space, it looks like this:
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19682
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19683 @c GNU Emacs 22
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19684 @smallexample
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19685 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19686 (defun yank-pop (&optional arg)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19687 "@dots{}"
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19688 (interactive "*p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19689 (if (not (eq last-command 'yank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19690 (error "Previous command was not a yank"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19691 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19692 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19693 (setq this-command 'yank)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19694 (unless arg (setq arg 1))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19695 (let ((inhibit-read-only t)
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19696 (before (< (point) (mark t))))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19697 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19698 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19699 (if before
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19700 (funcall (or yank-undo-function 'delete-region) (point) (mark t))
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19701 (funcall (or yank-undo-function 'delete-region) (mark t) (point)))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19702 (setq yank-undo-function nil)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19703 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19704 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19705 (set-marker (mark-marker) (point) (current-buffer))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19706 (insert-for-yank (current-kill arg))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19707 ;; Set the window start back where it was in the yank command,
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19708 ;; if possible.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19709 (set-window-start (selected-window) yank-window-start t)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19710 @end group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19711 @group
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19712 (if before
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19713 ;; This is like exchange-point-and-mark,
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19714 ;; but doesn't activate the mark.
73683
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19715 ;; It is cleaner to avoid activation, even though the command
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19716 ;; loop would deactivate the mark because we inserted text.
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19717 (goto-char (prog1 (mark t)
3e3a3e424e30 Minor fixes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73680
diff changeset
19718 (set-marker (mark-marker)
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19719 (point)
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19720 (current-buffer))))))
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19721 nil)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19722 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19723 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19724
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19725 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
19726 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
19727 only be used after a previous yank; otherwise an error message is
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19728 sent. This check uses the variable @code{last-command} which is set
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19729 by @code{yank} and is discussed elsewhere.
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
19730 (@xref{copy-region-as-kill}.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19731
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19732 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
19733 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
19734 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
19735 inserted by the previous yank and it is this text that will be
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19736 replaced.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19737
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19738 @code{funcall} calls its first argument as a function, passing
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19739 remaining arguments to it. The first argument is whatever the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19740 @code{or} expression returns. The two remaining arguments are the
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19741 positions of point and mark set by the preceding @code{yank} command.
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19742
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
19743 There is more, but that is the hardest part.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19744
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
19745 @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
19746 @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
19747 @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
19748 @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
19749
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
19750 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
19751 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
19752 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
19753 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
19754
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
19755 @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
19756 @appendix A Graph with Labelled Axes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19757
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19758 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
19759 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
19760 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
19761 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
19762 body itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19763
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19764 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19765 * Labelled Example::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
19766 * print-graph Varlist:: @code{let} expression in @code{print-graph}.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
19767 * print-Y-axis:: Print a label for the vertical axis.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
19768 * print-X-axis:: Print a horizontal label.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
19769 * Print Whole Graph:: The function to print a complete graph.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19770 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19771
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19772 @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
19773 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19774 @unnumberedsec Labelled Example Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19775 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19776
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19777 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
19778 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
19779 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
19780 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
19781
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19782 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19783 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19784 Set up code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19785
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19786 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19787 Print Y axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19788
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19789 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19790 Print body of graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19791
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 Print X axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19794 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19795
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19796 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19797 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
19798
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19799 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19800 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19801 10 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19802 *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19803 * *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19804 * **
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19805 * ***
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19806 5 - * *******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19807 * *** *******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19808 *************
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 1 - ****************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19811 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19812 1 5 10 15
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19813 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19814 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19815
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19816 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19817 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
19818 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
19819 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
19820
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19821 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19822 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19823 5 - *
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 *******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19826 ********** **
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19827 1 - **************
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 Jan June Jan
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19830 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19831 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19832
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19833 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
19834 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
19835 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
19836 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
19837 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
19838
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19839 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19840 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
19841 @code{print-graph} function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19842
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19843 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19844 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19845 (defun print-graph (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19846 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19847 (let ((height @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19848 @dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19849 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19850 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19851 (print-Y-axis height @dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19852 (graph-body-print numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19853 (print-X-axis @dots{} )))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19854 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19855 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19856
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19857 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
19858 in turn.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19859
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19860 @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
19861 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19862 @appendixsec The @code{print-graph} Varlist
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19863 @cindex @code{print-graph} varlist
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 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
19866 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
19867 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
19868 contents of its documentation string.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19869
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19870 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
19871 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
19872 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
19873 @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
19874 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
19875 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
19876 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
19877
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19878 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
19879 @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
19880 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
19881 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
19882 previous chapter.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19883
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19884 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
19885 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
19886 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
19887
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19888 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
19889 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
19890
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19891 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19892 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19893 (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
19894 (symbol-width (length graph-blank)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19895 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19896 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19897
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19898 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19899 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
19900
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
19901 @need 2000
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19902 @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
19903 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19904 @appendixsec The @code{print-Y-axis} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19905 @cindex Axis, print vertical
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19906 @cindex Y axis printing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19907 @cindex Vertical axis printing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19908 @cindex Print vertical axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19909
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19910 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
19911 the vertical axis that looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19912
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19913 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19914 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19915 10 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19916
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19917
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19918
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19919
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19920 5 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19921
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19922
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19923
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19924 1 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19925 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19926 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19927
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19928 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19929 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
19930 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
19931
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19932 @menu
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19933 * print-Y-axis in Detail::
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
19934 * Height of label:: What height for the Y axis?
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
19935 * Compute a Remainder:: How to compute the remainder of a division.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
19936 * Y Axis Element:: Construct a line for the Y axis.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
19937 * Y-axis-column:: Generate a list of Y axis labels.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
19938 * print-Y-axis Penultimate:: A not quite final version.
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19939 @end menu
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19940
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19941 @node print-Y-axis in Detail, Height of label, print-Y-axis, print-Y-axis
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19942 @ifnottex
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19943 @unnumberedsubsec The @code{print-Y-axis} Function in Detail
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19944 @end ifnottex
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19945
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19946 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
19947 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
19948 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
19949 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
19950 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
19951 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
19952 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
19953 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
19954 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
19955 five.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19956
73852
1629ec038cb6 (beginning of emacs-lisp-intro.texi): Add `other shell commands' to
Robert J. Chassell <bob@rattlesnake.com>
parents: 73767
diff changeset
19957 @node Height of label, Compute a Remainder, print-Y-axis in Detail, print-Y-axis
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19958 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19959 @unnumberedsubsec What height should the label be?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19960 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19961
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19962 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
19963 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
19964 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
19965 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
19966 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
19967 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
19968
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19969 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
19970 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
19971 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
19972 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
19973 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
19974 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
19975 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
19976 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
19977 is required.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19978
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19979 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
19980 divided into several smaller problems.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19981
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19982 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
19983 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
19984 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
19985
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19986 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
19987 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
19988 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
19989 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
19990 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
19991 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
19992 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
19993 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
19994
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19995 @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
19996 @appendixsubsec Side Trip: Compute a Remainder
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19997
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19998 @findex % @r{(remainder function)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19999 @cindex Remainder function, @code{%}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20000 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
20001 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
20002 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
20003 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
20004 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
20005 learn of the existence of @code{%} is to read about it in a book such
73554
d092f1092ef0 * emacs-lisp-intro.texi: Many changes since it turned out that
Robert J. Chassell <bob@rattlesnake.com>
parents: 72479
diff changeset
20006 as this or in the Emacs Lisp sources.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20007
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20008 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
20009 expressions:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20010
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20011 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20012 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20013 (% 7 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20014
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20015 (% 10 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20016 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20017 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20018
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20019 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20020 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
20021
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20022 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
20023 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
20024 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
20025
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20026 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20027 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20028 (zerop (% 7 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20029 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20030
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20031 (zerop (% 10 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20032 @result{} t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20033 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20034 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20035
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20036 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
20037 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
20038
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20039 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20040 (zerop (% height 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20041 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20042
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20043 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20044 (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
20045 'max numbers-list)}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20046
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20047 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
20048 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
20049 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
20050 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
20051 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
20052 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
20053 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
20054 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
20055 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
20056 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
20057
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20058 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20059 (* (1+ (/ height 5)) 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20060 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20061
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20062 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20063 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
20064
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20065 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20066 (* (1+ (/ 12 5)) 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20067 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20068
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20069 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
20070 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
20071 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
20072 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
20073 variable is @code{Y-axis-label-spacing}.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20076 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
20077 following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20078
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20079 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20080 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20081 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20082 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20083 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20084 (* (1+ (/ height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20085 Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20086 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20087 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20088
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20089 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20090 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
20091 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
20092 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
20093 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
20094
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20095 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
20096 @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
20097 @code{Y-axis-label-spacing}):
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20098 @vindex Y-axis-label-spacing
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20101 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20102 (defvar Y-axis-label-spacing 5
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20103 "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
20104 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20105
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20106 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20107 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20108 (let* ((height (apply 'max numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20109 (height-of-top-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20110 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20111 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20112 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20113 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20114 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20115 (* (1+ (/ height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20116 Y-axis-label-spacing)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20117 (symbol-width (length graph-blank))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20118 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20119 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20120 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20121
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20122 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20123 (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
20124 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
20125 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
20126 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
20127 more about @code{let*}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20128
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20129 @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
20130 @appendixsubsec Construct a Y Axis Element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20131
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20132 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
20133 @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
20134 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
20135 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
20136 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
20137 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
20138
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20139 @findex number-to-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20140 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
20141 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
20142 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
20143 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
20144 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20145
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20146 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20147 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20148 (length (number-to-string 35))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20149 @result{} 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20151 (length (number-to-string 100))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20152 @result{} 3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20153 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20154 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20155
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20156 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20157 (@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
20158 see this alternative name in various sources.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20159
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20160 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
20161 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
20162 This variable is defined with @code{defvar}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20163
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20164 @vindex Y-axis-tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20165 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20166 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20167 (defvar Y-axis-tic " - "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20168 "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
20169 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20170 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20171
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20172 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
20173 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
20174
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20175 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20176 (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
20177 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20178
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20179 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
20180 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
20181 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
20182
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20183 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
20184 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
20185 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
20186 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
20187 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
20188 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
20189 (just once) by @code{print-graph}.
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20192 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20193 (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
20194 "Construct a NUMBERed label element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20195 A numbered element looks like this ` 5 - ',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20196 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
20197 the element for the largest number."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20198 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20199 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20200 (let* ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20201 (- full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20202 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20203 (concat (number-to-string number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20204 Y-axis-tic)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20205 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20206 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20207 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20208 (make-string leading-spaces ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20209 (number-to-string number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20210 Y-axis-tic)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20211 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20212 @end smallexample
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 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
20215 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
20216
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20217 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
20218 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
20219 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
20220
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20221 @findex make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20222 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
20223 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
20224 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
20225 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
20226 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
20227 elisp, The GNU Emacs Lisp Reference Manual}, for a description of the
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
20228 syntax for characters. (Of course, you might want to replace the
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
20229 blank space by some other character @dots{} You know what to do.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20230
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20231 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
20232 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
20233 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
20234
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20235 @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
20236 @appendixsubsec Create a Y Axis Column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20237
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20238 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
20239 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
20240 as the label for the vertical axis:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20241
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20242 @findex Y-axis-column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20243 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20244 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20245 (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
20246 "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
20247 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
20248 (let (Y-axis)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20249 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20250 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20251 (while (> height 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20252 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20253 ;; @r{Insert label.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20254 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20255 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20256 (Y-axis-element height width-of-label)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20257 Y-axis))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20258 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20259 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20260 ;; @r{Else, insert blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20261 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20262 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20263 (make-string width-of-label ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20264 Y-axis)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20265 (setq height (1- height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20266 ;; @r{Insert base line.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20267 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20268 (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
20269 (nreverse Y-axis)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20270 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20271 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20272
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20273 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
20274 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
20275 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
20276 @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
20277 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
20278 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
20279 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
20280
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
20281 @need 2000
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20282 @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
20283 @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
20284
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20285 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
20286 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
20287
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20288 @findex print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20289 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20290 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20291 (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
20292 "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
20293 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
20294 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
20295 ;; 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
20296 ;; are passed by `print-graph'.
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20299 (let ((start (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20300 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20301 (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
20302 ;; @r{Place point ready for inserting graph.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20303 (goto-char start)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20304 ;; @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
20305 (forward-char full-Y-label-width)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20306 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20307 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20308
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20309 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
20310 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
20311 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
20312 the graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20313
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20314 You can test @code{print-Y-axis}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20315
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20316 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20317 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20318 Install
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20319
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20320 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20321 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20322 Y-axis-label-spacing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20323 Y-axis-tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20324 Y-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20325 Y-axis-column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20326 print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20327 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20328 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20329
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20330 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20331 Copy the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20332
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20333 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20334 (print-Y-axis 12 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20335 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20336
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20337 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20338 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
20339 want the axis labels to start.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20340
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20341 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20342 Type @kbd{M-:} (@code{eval-expression}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20343
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20344 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20345 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
20346 with @kbd{C-y} (@code{yank)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20347
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20348 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20349 Press @key{RET} to evaluate the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20350 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20351
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
20352 Emacs will print labels vertically, the top one being @w{@samp{10 -@w{
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
20353 }}}. (The @code{print-graph} function will pass the value of
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
20354 @code{height-of-top-line}, which in this case will end up as 15,
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
20355 thereby getting rid of what might appear as a bug.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20356
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
20357 @need 2000
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20358 @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
20359 @appendixsec The @code{print-X-axis} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20360 @cindex Axis, print horizontal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20361 @cindex X axis printing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20362 @cindex Print horizontal axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20363 @cindex Horizontal axis printing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20364
70609
bd74271e8d03 Fix spelling errors.
Eli Zaretskii <eliz@gnu.org>
parents: 68640
diff changeset
20365 X axis labels are much like Y axis labels, except that the ticks are on a
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20366 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
20367
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20368 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20369 @group
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 1 5 10 15
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20372 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20373 @end smallexample
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 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
20376 several blank spaces. These spaces provide room in rows above for the Y
70609
bd74271e8d03 Fix spelling errors.
Eli Zaretskii <eliz@gnu.org>
parents: 68640
diff changeset
20377 axis labels. The second, third, fourth, and subsequent ticks are all
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20378 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
20379
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20380 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
20381 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
20382 @code{X-axis-label-spacing}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20383
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20384 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
20385 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
20386 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
20387 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
20388
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20389 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
20390 * Similarities differences:: Much like @code{print-Y-axis}, but not exactly.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
20391 * X Axis Tic Marks:: Create tic marks for the horizontal axis.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20392 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20393
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20394 @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
20395 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20396 @unnumberedsubsec Similarities and differences
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20397 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20398
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20399 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
20400 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
20401 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
20402 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
20403 @code{print-X-axis} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20404
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20405 This is a three step process:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20406
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20407 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20408 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20409 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
20410
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20411 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20412 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
20413
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20414 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20415 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
20416 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
20417 @code{print-X-axis-numbered-line}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20418 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20419
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20420 @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
20421 @appendixsubsec X Axis Tic Marks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20422
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20423 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
20424 the tic marks themselves and their spacing:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20425
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20426 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20427 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20428 (defvar X-axis-label-spacing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20429 (if (boundp 'graph-blank)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20430 (* 5 (length graph-blank)) 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20431 "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
20432 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20433 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20434
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20435 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20436 (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
20437 @code{defvar}. The @code{boundp} predicate checks whether it has
73767
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
20438 already been set; @code{boundp} returns @code{nil} if it has not. If
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
20439 @code{graph-blank} were unbound and we did not use this conditional
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
20440 construction, in a recent GNU Emacs, we would enter the debugger and
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
20441 see an error message saying @samp{@w{Debugger entered--Lisp error:}
a44deabfa735 Finish minor changes seen from DVI output.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73720
diff changeset
20442 @w{(void-variable graph-blank)}}.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20443
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20444 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20445 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
20446
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20447 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20448 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20449 (defvar X-axis-tic-symbol "|"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20450 "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
20451 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20452 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20453
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20454 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20455 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
20456
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20457 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20458 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20459 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20460
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20461 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
20462 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
20463
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20464 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
20465 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
20466 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
20467
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20468 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20469 The code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20470
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20471 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20472 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20473 ;;; X-axis-tic-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20474 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20475 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20476 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20477 ;; @r{Make a string of blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20478 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20479 (length X-axis-tic-symbol))
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 ;; @r{Concatenate blanks with tic symbol.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20482 X-axis-tic-symbol)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20483 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20484 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20485 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20486
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20487 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
20488 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
20489 @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
20490
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20491 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20492 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
20493 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20494
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20495 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20496 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20497 ;; X-axis-leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20498 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20499 (make-string full-Y-label-width ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20500 @dots{}
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 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20503
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20504 We also need to determine the length of the horizontal axis, which is
70609
bd74271e8d03 Fix spelling errors.
Eli Zaretskii <eliz@gnu.org>
parents: 68640
diff changeset
20505 the length of the numbers list, and the number of ticks in the horizontal
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20506 axis:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20507
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20508 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20509 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20510 ;; X-length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20511 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20512 (length numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20513 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20514
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20515 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20516 ;; tic-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20517 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20518 (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20519 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20520
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20521 @group
70609
bd74271e8d03 Fix spelling errors.
Eli Zaretskii <eliz@gnu.org>
parents: 68640
diff changeset
20522 ;; number-of-X-ticks
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20523 (if (zerop (% (X-length tic-width)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20524 (/ (X-length tic-width))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20525 (1+ (/ (X-length tic-width))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20526 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20527 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20528
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20529 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20530 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
20531
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20532 @findex print-X-axis-tic-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20533 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20534 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20535 (defun print-X-axis-tic-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20536 (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
70609
bd74271e8d03 Fix spelling errors.
Eli Zaretskii <eliz@gnu.org>
parents: 68640
diff changeset
20537 "Print ticks for X axis."
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20538 (insert X-axis-leading-spaces)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20539 (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
20540 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20541 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20542 ;; @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
20543 (insert (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20544 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20545 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20546 ;; @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
20547 (* 2 (length X-axis-tic-symbol)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20548 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20549 X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20550 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20551 @group
70609
bd74271e8d03 Fix spelling errors.
Eli Zaretskii <eliz@gnu.org>
parents: 68640
diff changeset
20552 ;; @r{Insert remaining ticks.}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20553 (while (> number-of-X-tics 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20554 (insert X-axis-tic-element)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20555 (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
20556 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20557 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20558
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20559 The line of numbers is equally straightforward:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20560
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20561 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20562 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
20563
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20564 @findex X-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20565 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20566 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20567 (defun X-axis-element (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20568 "Construct a numbered X axis element."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20569 (let ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20570 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20571 (length (number-to-string number)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20572 (concat (make-string leading-spaces ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20573 (number-to-string number))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20574 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20575 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20576
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20577 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
20578 the number ``1'' under the first column:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20579
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20580 @findex print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20581 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20582 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20583 (defun print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20584 (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
20585 "Print line of X-axis numbers"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20586 (let ((number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20587 (insert X-axis-leading-spaces)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20588 (insert "1")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20589 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20590 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20591 (insert (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20592 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20593 ;; @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
20594 (- (* symbol-width X-axis-label-spacing) 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20595 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20596 (number-to-string number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20597 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20598 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20599 ;; @r{Insert remaining numbers.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20600 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20601 (while (> number-of-X-tics 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20602 (insert (X-axis-element number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20603 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20604 (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
20605 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20606 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20607
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20608 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
20609 @code{print-X-axis-tic-line} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20610 @code{print-X-axis-numbered-line}.
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 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
20613 @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
20614 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
20615 separates the two lines.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20616
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20617 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
20618 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
20619
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20620 @findex print-X-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20621 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20622 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20623 (defun print-X-axis (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20624 "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
20625 (let* ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20626 (make-string full-Y-label-width ? ))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20627 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20628 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20629 ;; 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
20630 (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
20631 (X-length (length numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20632 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20633 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20634 (X-tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20635 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20636 (make-string
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 ;; @r{Make a string of blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20640 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20641 (length X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20642 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20643 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20644 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20645 ;; @r{Concatenate blanks with tic symbol.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20646 X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20647 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20648 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20649 (tic-number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20650 (if (zerop (% X-length tic-width))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20651 (/ X-length tic-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20652 (1+ (/ X-length tic-width)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20653 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20654 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20655 (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
20656 (insert "\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20657 (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
20658 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20659 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20660
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20661 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20662 You can test @code{print-X-axis}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20663
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20664 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20665 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20666 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
20667 @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
20668 @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
20669
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20670 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20671 Copy the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20672
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20673 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20674 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20675 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20676 (let ((full-Y-label-width 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20677 (symbol-width 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20678 (print-X-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20679 '(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
20680 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20681 @end smallexample
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20684 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
20685 want the axis labels to start.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20686
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20687 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20688 Type @kbd{M-:} (@code{eval-expression}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20690 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20691 Yank the test expression into the minibuffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20692 with @kbd{C-y} (@code{yank)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20693
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20694 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20695 Press @key{RET} to evaluate the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20696 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20697
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20698 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20699 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
20700 @sp 1
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20701
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20702 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20703 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20704 | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20705 1 5 10 15 20
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20706 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20707 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20708
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20709 @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
20710 @appendixsec Printing the Whole Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20711 @cindex Printing the whole graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20712 @cindex Whole graph printing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20713 @cindex Graph, printing all
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20714
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20715 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
20716
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20717 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
20718 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
20719 Axes}), but with additions.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20722 Here is the outline:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20723
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20724 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20725 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20726 (defun print-graph (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20727 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20728 (let ((height @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20729 @dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20730 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20731 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20732 (print-Y-axis height @dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20733 (graph-body-print numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20734 (print-X-axis @dots{} )))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20735 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20736 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20737
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20738 @menu
73854
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
20739 * The final version:: A few changes.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
20740 * Test print-graph:: Run a short test.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
20741 * Graphing words in defuns:: Executing the final code.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
20742 * lambda:: How to write an anonymous function.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
20743 * mapcar:: Apply a function to elements of a list.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
20744 * Another Bug:: Yet another bug @dots{} most insidious.
55e5dc416293 Copy descriptions from detailed master menu to menus within body.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73852
diff changeset
20745 * Final printed graph:: The graph itself!
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20746 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20747
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20748 @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
20749 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20750 @unnumberedsubsec Changes for the Final Version
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20751 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20752
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20753 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
20754 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
20755 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
20756 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
20757 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
20758
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20759 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20760 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
20761 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
20762 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20763
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20764 @findex Y-axis-column @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20765 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20766 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20767 ;;; @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20768 (defun Y-axis-column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20769 (height width-of-label &optional vertical-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20770 "Construct list of labels for Y axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20771 HEIGHT is maximum height of graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20772 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
20773 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
20774 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
20775 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
20776 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
20777 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20778 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20779 (let (Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20780 (number-per-line (or vertical-step 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20781 (while (> height 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20782 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20783 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20784 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20785 ;; @r{Insert label.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20786 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20787 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20788 (Y-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20789 (* height number-per-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20790 width-of-label)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20791 Y-axis))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20792 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20793 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20794 ;; @r{Else, insert blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20795 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20796 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20797 (make-string width-of-label ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20798 Y-axis)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20799 (setq height (1- height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20800 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20801 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20802 ;; @r{Insert base line.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20803 (setq Y-axis (cons (Y-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20804 (or vertical-step 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20805 width-of-label)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20806 Y-axis))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20807 (nreverse Y-axis)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20808 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20809 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20810
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20811 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
20812 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
20813 @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
20814
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20815 @findex graph-body-print @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20816 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20817 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20818 ;;; @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20819 (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
20820 "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
20821 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
20822 HEIGHT is maximum height of graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20823 SYMBOL-WIDTH is number of each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20824 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20825 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20826 (let (from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20827 (while numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20828 (setq from-position (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20829 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20830 (column-of-graph height (car numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20831 (goto-char from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20832 (forward-char symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20833 @end group
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 ;; @r{Draw graph column by column.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20836 (sit-for 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20837 (setq numbers-list (cdr numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20838 ;; @r{Place point for X axis labels.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20839 (forward-line height)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20840 (insert "\n")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20841 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20842 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20843
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20844 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20845 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
20846
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20847 @findex print-graph @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20848 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20849 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20850 ;;; @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20851 (defun print-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20852 (numbers-list &optional vertical-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20853 "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
20854 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
20855 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20858 Optionally, VERTICAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20859 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
20860 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
20861 each row is five units."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20862 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20863 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20864 (let* ((symbol-width (length graph-blank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20865 ;; @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
20866 ;; @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
20867 (height (apply 'max numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20868 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20869 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20870 (height-of-top-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20871 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20872 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20873 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20874 (* (1+ (/ height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20875 Y-axis-label-spacing)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20876 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20877 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20878 (vertical-step (or vertical-step 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20879 (full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20880 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20881 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20882 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20883 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20884 (number-to-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20885 (* height-of-top-line vertical-step))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20886 Y-axis-tic))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20887 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20888
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 (print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20891 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
20892 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20893 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20894 (graph-body-print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20895 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
20896 (print-X-axis numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20897 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20898 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20899
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20900 @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
20901 @appendixsubsec Testing @code{print-graph}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20902
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20903 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20904 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
20905
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20906 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20907 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20908 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
20909 @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
20910 rest of the code.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20911
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20912 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20913 Copy the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20914
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20915 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20916 (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
20917 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20918
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20919 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20920 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
20921 want the axis labels to start.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20922
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20923 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20924 Type @kbd{M-:} (@code{eval-expression}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20925
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20926 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20927 Yank the test expression into the minibuffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20928 with @kbd{C-y} (@code{yank)}.
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20931 Press @key{RET} to evaluate the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20932 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20933
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20934 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20935 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
20936
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20937 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20938 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20939 10 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20940
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 *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20943 ** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20944 5 - **** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20945 **** ***
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20946 * *********
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20947 ************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20948 1 - *************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20949
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20950 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20951 1 5 10 15
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20952 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20953 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20954
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
20955 @need 1200
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20956 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
20957 @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
20958
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20959 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20960 (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
20961 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20962
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20963 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20964 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20965 The graph looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20966
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20967 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20968 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20969 20 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20970
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20971
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20972 *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20973 ** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20974 10 - **** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20975 **** ***
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20976 * *********
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20977 ************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20978 2 - *************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20979
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20980 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20981 1 5 10 15
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20982 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20983 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20984
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20985 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20986 (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
20987 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
20988 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
20989
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20990 @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
20991 @appendixsubsec Graphing Numbers of Words and Symbols
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20992
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20993 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
20994 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
20995 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
20996 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
20997
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20998 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
20999 requisite code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21001 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21002 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
21003 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
21004 following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21005
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21006 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21007 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21008 (setq top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21009 '(10 20 30 40 50
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21010 60 70 80 90 100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21011 110 120 130 140 150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21012 160 170 180 190 200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21013 210 220 230 240 250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21014 260 270 280 290 300)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21015 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21016 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21017
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21018 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21019 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
21020
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21021 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21022 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21023 Evaluate the following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21024
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21025 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21026 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21027 (setq list-for-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21028 (defuns-per-range
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21029 (sort
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21030 (recursive-lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21031 (directory-files "/usr/local/emacs/lisp"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21032 t ".+el$"))
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 top-of-ranges))
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 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21037
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21038 @noindent
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21039 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
21040 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
21041 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
21042
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21043 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21044 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21045 (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
21046 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
21047 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21048 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21049
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21050 @noindent
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21051 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
21052 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
21053 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
21054 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
21055
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21056 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
21057 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
21058
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21059 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
21060 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
21061 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
21062 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
21063
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21064 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
21065 one-fiftieth its present value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21066
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21067 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
21068 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
21069
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21070 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21071 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21072 (defun one-fiftieth (full-range)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21073 "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
21074 (mapcar '(lambda (arg) (/ arg 50)) full-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21075 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21076 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21077
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21078 @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
21079 @appendixsubsec A @code{lambda} Expression: Useful Anonymity
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21080 @cindex Anonymous function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21081 @findex lambda
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21082
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21083 @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
21084 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
21085 include its whole body.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21086
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21087 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21088 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21089 Thus,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21090
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21091 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21092 (lambda (arg) (/ arg 50))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21093 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21094
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21095 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21096 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
21097 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
21098
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
21099 @need 1200
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21100 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
21101 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
21102 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
21103 equivalent of @code{multiply-by-seven} is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21104
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21105 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21106 (lambda (number) (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21107 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21108
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21109 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21110 (@xref{defun, , The @code{defun} Special Form}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21111
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21112 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21113 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21114 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
21115
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21116 @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
21117 @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
21118 @c clear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21119 @c set print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21120 @c lambda example diagram #1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21121 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21122 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21123 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21124 (multiply-by-seven 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21125 \_______________/ ^
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21126 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21127 function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21128 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21129 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21130 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21131 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21132 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21133 @tex
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
21134 @center @image{lambda-1}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21135 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21136 % \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
21137 % \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
21138 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21139 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21140 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21141 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21142 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21143 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21144 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21145 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21146 (multiply-by-seven 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21147 \_______________/ ^
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21148 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21149 function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21150 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21151 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21152 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21153 @end ifclear
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21156 This expression returns 21.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21157
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21158 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21159 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21160 Similarly, we can write:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21161
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21162 @c lambda example diagram #2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21163 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21164 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21165 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21166 ((lambda (number) (* 7 number)) 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21167 \____________________________/ ^
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21168 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21169 anonymous function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21170 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21171 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21172 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21173 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21174 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21175 @tex
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
21176 @center @image{lambda-2}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21177 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21178 % \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
21179 % \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
21180 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21181 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21182 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21183 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21184 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21185 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21186 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21187 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21188 ((lambda (number) (* 7 number)) 3)
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 anonymous function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21192 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21193 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21194 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21195 @end ifclear
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21198 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21199 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
21200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21201 @c lambda example diagram #3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21202 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21203 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21204 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21205 ((lambda (arg) (/ arg 50)) 100)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21206 \______________________/ \_/
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21207 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21208 anonymous function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21209 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21210 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21211 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21212 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21213 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21214 @tex
73706
ae44d5bc9d37 More minor changes.
Robert J. Chassell <bob@rattlesnake.com>
parents: 73683
diff changeset
21215 @center @image{lambda-3}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21216 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21217 % \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
21218 % \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
21219 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21220 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21221 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21222 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21223 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21224 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21225 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21226 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21227 ((lambda (arg) (/ arg 50)) 100)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21228 \______________________/ \_/
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21229 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21230 anonymous function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21231 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21232 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21233 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21234 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21235
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21236 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21237 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
21238 divides that number by 50.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21239
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21240 @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
21241 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
21242 expressions derive from the Lambda Calculus.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21243
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21244 @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
21245 @appendixsubsec The @code{mapcar} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21246 @findex mapcar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21247
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21248 @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
21249 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
21250 a sequence.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21251
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21252 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
21253 `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
21254 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
21255 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
21256 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
21257 first of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21258
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21259 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21260 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21261 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21262
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21263 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21264 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21265 (mapcar '1+ '(2 4 6))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21266 @result{} (3 5 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21267 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21268 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21269
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21270 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21271 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
21272 @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
21273
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21274 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
21275 all the remaining.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21276 (@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
21277 @code{apply}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21278
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21279 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21280 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
21281 anonymous function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21282
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21283 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21284 (lambda (arg) (/ arg 50))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21285 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21286
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21287 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21288 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
21289 @code{list-for-graph}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21290
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21291 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21292 The whole expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21293
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21294 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21295 (mapcar '(lambda (arg) (/ arg 50)) full-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21296 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21297
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21298 @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
21299 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
21300
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21301 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
21302 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
21303 element in @code{list-for-graph}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21304
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21305 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21306 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21307 (setq fiftieth-list-for-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21308 (one-fiftieth list-for-graph))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21309 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21310 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21311
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21312 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21313 The resulting list looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21314
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21315 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21316 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21317 (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
21318 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
21319 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21320 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21321
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21322 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21323 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
21324 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
21325 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
21326 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
21327
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21328 @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
21329 @appendixsubsec Another Bug @dots{} Most Insidious
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21330 @cindex Bug, most insidious type
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21331 @cindex Insidious type of bug
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21332
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21333 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
21334 @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
21335 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
21336 @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
21337 @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
21338
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21339 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
21340 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
21341 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
21342 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
21343 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
21344 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
21345 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
21346 eventually. A hard maxim to follow.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21347
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21348 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
21349 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
21350 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
21351 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
21352 a little thought.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21355 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
21356
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21357 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21358 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21359 (defun print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21360 (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
21361 &optional horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21362 "Print line of X-axis numbers"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21363 (let ((number X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21364 (horizontal-step (or horizontal-step 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21365 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21366 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21367 (insert X-axis-leading-spaces)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21368 ;; @r{Delete extra leading spaces.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21369 (delete-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21370 (- (1-
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21371 (length (number-to-string horizontal-step)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21372 (insert (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21373 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21374 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21375 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21376 ;; @r{Insert white space.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21377 (- (* symbol-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21378 X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21379 (1-
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21380 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21381 (number-to-string horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21382 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21383 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21384 (number-to-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21385 (* number horizontal-step))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21386 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21387 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21388 ;; @r{Insert remaining numbers.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21389 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21390 (while (> number-of-X-tics 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21391 (insert (X-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21392 (* number horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21393 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21394 (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
21395 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21396 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21397
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21398 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21399 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
21400 @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
21401 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
21402 (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
21403
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21404 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21405 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21406 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21407 (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
21408 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21409 (print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21410 tic-number leading-spaces horizontal-step))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21411 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21412 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21413
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21414 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21415 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21416 (defun print-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21417 (numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21418 &optional vertical-step horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21419 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21420 (print-X-axis numbers-list horizontal-step))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21421 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21422 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21423 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21424
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21425 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21426 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21427 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21428 (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
21429 "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
21430 Optionally, HORIZONTAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21431 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
21432 each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21433 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21434 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21435 ;; 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
21436 ;; are passed by `print-graph'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21437 (let* ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21438 (make-string full-Y-label-width ? ))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21439 ;; 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
21440 (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
21441 (X-length (length numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21442 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21443 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21444 (X-tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21445 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21446 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21447 ;; @r{Make a string of blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21448 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21449 (length X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21450 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21451 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21452 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21453 ;; @r{Concatenate blanks with tic symbol.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21454 X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21455 (tic-number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21456 (if (zerop (% X-length tic-width))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21457 (/ X-length tic-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21458 (1+ (/ X-length tic-width)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21459 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21460
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21461 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21462 (print-X-axis-tic-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21463 tic-number leading-spaces X-tic)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21464 (insert "\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21465 (print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21466 tic-number leading-spaces horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21467 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21468 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21469
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21470 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21471 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21472 (defun print-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21473 (numbers-list &optional vertical-step horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21474 "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
21475 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
21476 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21477
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21478 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21479 Optionally, VERTICAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21480 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
21481 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
21482 each row is five units.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21483 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21484
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21485 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21486 Optionally, HORIZONTAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21487 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
21488 each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21489 (let* ((symbol-width (length graph-blank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21490 ;; @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
21491 ;; @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
21492 (height (apply 'max numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21493 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21494 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21495 (height-of-top-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21496 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21497 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21498 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21499 (* (1+ (/ height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21500 Y-axis-label-spacing)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21501 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21502 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21503 (vertical-step (or vertical-step 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21504 (full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21505 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21506 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21507 (number-to-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21508 (* height-of-top-line vertical-step))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21509 Y-axis-tic))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21510 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21511 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21512 (print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21513 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
21514 (graph-body-print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21515 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
21516 (print-X-axis numbers-list horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21517 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21518 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21519 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21520
57334
37199d6ac2c7 Add minor footnotes saying ' is an abbreviation for quote.
Robert J. Chassell <bob@rattlesnake.com>
parents: 56940
diff changeset
21521 @c qqq
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21522 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21523 Graphing Definitions Re-listed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21524
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21525 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21526 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
21527
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21528 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21529 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21530 (defvar top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21531 '(10 20 30 40 50
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21532 60 70 80 90 100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21533 110 120 130 140 150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21534 160 170 180 190 200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21535 210 220 230 240 250)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21536 "List specifying ranges for `defuns-per-range'.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21537 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21540 (defvar graph-symbol "*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21541 "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
21542 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21543
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21544 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21545 (defvar graph-blank " "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21546 "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
21547 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
21548 as graph-symbol.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21549 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21552 (defvar Y-axis-tic " - "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21553 "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
21554 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21555
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21556 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21557 (defvar Y-axis-label-spacing 5
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21558 "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
21559 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21560
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21561 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21562 (defvar X-axis-tic-symbol "|"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21563 "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
21564 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21565
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21566 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21567 (defvar X-axis-label-spacing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21568 (if (boundp 'graph-blank)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21569 (* 5 (length graph-blank)) 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21570 "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
21571 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21572 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21573
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21574 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21575 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21576 (defun count-words-in-defun ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21577 "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
21578 (beginning-of-defun)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21579 (let ((count 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21580 (end (save-excursion (end-of-defun) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21581 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21582
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21583 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21584 (while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21585 (and (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21586 (re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21587 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21588 end t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21589 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21590 count))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21591 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21592 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21593
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21594 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21595 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21596 (defun lengths-list-file (filename)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21597 "Return list of definitions' lengths within FILE.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21598 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
21599 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
21600 symbols in one function definition."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21601 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21602
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21603 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21604 (message "Working on `%s' ... " filename)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21605 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21606 (let ((buffer (find-file-noselect filename))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21607 (lengths-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21608 (set-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21609 (setq buffer-read-only t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21610 (widen)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21611 (goto-char (point-min))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21612 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21613
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21614 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21615 (while (re-search-forward "^(defun" nil t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21616 (setq lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21617 (cons (count-words-in-defun) lengths-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21618 (kill-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21619 lengths-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21620 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21621 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21622
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21623 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21624 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21625 (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
21626 "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
21627 (let (lengths-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21628 ;;; @r{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21629 (while list-of-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21630 (setq lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21631 (append
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21632 lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21633 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21634 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21635 ;;; @r{Generate a lengths' list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21636 (lengths-list-file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21637 (expand-file-name (car list-of-files)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21638 ;;; @r{Make files' list shorter.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21639 (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
21640 ;;; @r{Return final value of lengths' list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21641 lengths-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21642 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21643 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21644
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21645 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21646 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21647 (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
21648 "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
21649 (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
21650 (number-within-range 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21651 defuns-per-range-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21652 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21655 ;; @r{Outer loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21656 (while top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21657
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21658 ;; @r{Inner loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21659 (while (and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21660 ;; @r{Need number for numeric test.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21661 (car sorted-lengths)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21662 (< (car sorted-lengths) top-of-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21663
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21664 ;; @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
21665 (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
21666 (setq sorted-lengths (cdr sorted-lengths)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21667 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21668
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21669 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21670 ;; @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
21671
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21672 (setq defuns-per-range-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21673 (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
21674 (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
21675
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21676 ;; @r{Move to next range.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21677 (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
21678 ;; @r{Specify next top of range value.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21679 (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
21680 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21681
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21682 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21683 ;; @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
21684 ;; @r{ the largest top-of-range value.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21685 (setq defuns-per-range-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21686 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21687 (length sorted-lengths)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21688 defuns-per-range-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21690 ;; @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
21691 ;; @r{ smallest to largest.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21692 (nreverse defuns-per-range-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21693 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21694 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21695
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21696 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21697 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21698 (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
21699 "Return list of MAX-GRAPH-HEIGHT strings;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21700 ACTUAL-HEIGHT are graph-symbols.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21701 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
21702 of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21703 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
21704 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
21705 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21706
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21707 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21708 (let ((insert-list nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21709 (number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21710 (- max-graph-height actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21711
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21712 ;; @r{Fill in @code{graph-symbols}.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21713 (while (> actual-height 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21714 (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
21715 (setq actual-height (1- actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21716 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21717
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21718 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21719 ;; @r{Fill in @code{graph-blanks}.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21720 (while (> number-of-top-blanks 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21721 (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
21722 (setq number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21723 (1- number-of-top-blanks)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21724
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21725 ;; @r{Return whole list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21726 insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21727 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21728 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21729
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21730 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21731 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21732 (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
21733 "Construct a NUMBERed label element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21734 A numbered element looks like this ` 5 - ',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21735 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
21736 the element for the largest number."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21737 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21738 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21739 (let* ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21740 (- full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21741 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21742 (concat (number-to-string number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21743 Y-axis-tic)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21744 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21745 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21746 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21747 (make-string leading-spaces ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21748 (number-to-string number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21749 Y-axis-tic)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21750 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21751 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21752
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21753 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21754 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21755 (defun print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21756 (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
21757 "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
21758 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
21759 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
21760 Optionally, print according to VERTICAL-STEP."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21761 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21762 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21763 ;; 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
21764 ;; are passed by `print-graph'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21765 (let ((start (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21766 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21767 (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
21768 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21769 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21770 ;; @r{Place point ready for inserting graph.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21771 (goto-char start)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21772 ;; @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
21773 (forward-char full-Y-label-width)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21774 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21775 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21776
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21777 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21778 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21779 (defun print-X-axis-tic-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21780 (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
70609
bd74271e8d03 Fix spelling errors.
Eli Zaretskii <eliz@gnu.org>
parents: 68640
diff changeset
21781 "Print ticks for X axis."
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21782 (insert X-axis-leading-spaces)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21783 (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
21784 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21785 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21786 ;; @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
21787 (insert (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21788 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21789 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21790 ;; @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
21791 (* 2 (length X-axis-tic-symbol)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21792 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21793 X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21794 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21795 @group
70609
bd74271e8d03 Fix spelling errors.
Eli Zaretskii <eliz@gnu.org>
parents: 68640
diff changeset
21796 ;; @r{Insert remaining ticks.}
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21797 (while (> number-of-X-tics 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21798 (insert X-axis-tic-element)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21799 (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
21800 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21801 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21802
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21803 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21804 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21805 (defun X-axis-element (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21806 "Construct a numbered X axis element."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21807 (let ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21808 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21809 (length (number-to-string number)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21810 (concat (make-string leading-spaces ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21811 (number-to-string number))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21812 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21813 @end smallexample
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21816 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21817 (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
21818 "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
21819 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
21820 HEIGHT is maximum height of graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21821 SYMBOL-WIDTH is number of each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21822 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21823 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21824 (let (from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21825 (while numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21826 (setq from-position (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21827 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21828 (column-of-graph height (car numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21829 (goto-char from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21830 (forward-char symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21831 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21832 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21833 ;; @r{Draw graph column by column.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21834 (sit-for 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21835 (setq numbers-list (cdr numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21836 ;; @r{Place point for X axis labels.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21837 (forward-line height)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21838 (insert "\n")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21839 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21840 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21841
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21842 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21843 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21844 (defun Y-axis-column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21845 (height width-of-label &optional vertical-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21846 "Construct list of labels for Y axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21847 HEIGHT is maximum height of graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21848 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
21849 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21850 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21851 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
21852 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
21853 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
21854 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
21855 (let (Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21856 (number-per-line (or vertical-step 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21857 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21858 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21859 (while (> height 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21860 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21861 ;; @r{Insert label.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21862 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21863 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21864 (Y-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21865 (* height number-per-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21866 width-of-label)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21867 Y-axis))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21868 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21869 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21870 ;; @r{Else, insert blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21871 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21872 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21873 (make-string width-of-label ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21874 Y-axis)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21875 (setq height (1- height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21876 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21877 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21878 ;; @r{Insert base line.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21879 (setq Y-axis (cons (Y-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21880 (or vertical-step 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21881 width-of-label)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21882 Y-axis))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21883 (nreverse Y-axis)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21884 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21885 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21886
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21887 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21888 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21889 (defun print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21890 (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
21891 &optional horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21892 "Print line of X-axis numbers"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21893 (let ((number X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21894 (horizontal-step (or horizontal-step 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21895 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21896 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21897 (insert X-axis-leading-spaces)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21898 ;; line up number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21899 (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
21900 (insert (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21901 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21902 ;; @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
21903 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21904 (1- (length (number-to-string horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21905 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21906 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21907 (number-to-string (* number horizontal-step))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21908 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21909 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21910 ;; @r{Insert remaining numbers.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21911 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21912 (while (> number-of-X-tics 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21913 (insert (X-axis-element (* number horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21914 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21915 (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
21916 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21917 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21918
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21919 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21920 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21921 (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
21922 "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
21923 Optionally, HORIZONTAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21924 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
21925 each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21926 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21927 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21928 ;; 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
21929 ;; are passed by `print-graph'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21930 (let* ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21931 (make-string full-Y-label-width ? ))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21932 ;; 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
21933 (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
21934 (X-length (length numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21935 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21936 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21937 (X-tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21938 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21939 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21940 ;; @r{Make a string of blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21941 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21942 (length X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21943 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21944 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21945 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21946 ;; @r{Concatenate blanks with tic symbol.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21947 X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21948 (tic-number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21949 (if (zerop (% X-length tic-width))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21950 (/ X-length tic-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21951 (1+ (/ X-length tic-width)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21952 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21953
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21954 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21955 (print-X-axis-tic-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21956 tic-number leading-spaces X-tic)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21957 (insert "\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21958 (print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21959 tic-number leading-spaces horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21960 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21961 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21962
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21963 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21964 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21965 (defun one-fiftieth (full-range)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21966 "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
21967 (mapcar '(lambda (arg) (/ arg 50)) full-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21968 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21969 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21970
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21971 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21972 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21973 (defun print-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21974 (numbers-list &optional vertical-step horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21975 "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
21976 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
21977 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21978
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21979 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21980 Optionally, VERTICAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21981 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
21982 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
21983 each row is five units.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21984 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21985
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21986 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21987 Optionally, HORIZONTAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21988 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
21989 each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21990 (let* ((symbol-width (length graph-blank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21991 ;; @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
21992 ;; @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
21993 (height (apply 'max numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21994 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21995 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21996 (height-of-top-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21997 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21998 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21999 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22000 (* (1+ (/ height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22001 Y-axis-label-spacing)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22002 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22003 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22004 (vertical-step (or vertical-step 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22005 (full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22006 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22007 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22008 (number-to-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22009 (* height-of-top-line vertical-step))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22010 Y-axis-tic))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22011 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22012 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22013
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22014 (print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22015 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
22016 (graph-body-print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22017 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
22018 (print-X-axis numbers-list horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22019 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22020 @end smallexample
57334
37199d6ac2c7 Add minor footnotes saying ' is an abbreviation for quote.
Robert J. Chassell <bob@rattlesnake.com>
parents: 56940
diff changeset
22021 @c qqq
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22022 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22023
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22024 @page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22025 @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
22026 @appendixsubsec The Printed Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22027
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22028 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
22029 like this:
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22030 @sp 1
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22031
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22032 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22033 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22034 (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
22035 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22036 @end smallexample
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22037 @sp 1
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22038
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22039 @noindent
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22040 Here is the graph:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22041 @sp 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22042
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22043 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22044 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22045 1000 - *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22046 **
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22047 **
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22048 **
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22049 **
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22050 750 - ***
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22051 ***
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22052 ***
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22053 ***
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22054 ****
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22055 500 - *****
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22056 ******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22057 ******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22058 ******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22059 *******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22060 250 - ********
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22061 ********* *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22062 *********** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22063 ************* *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22064 50 - ***************** * *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22065 | | | | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22066 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
22067 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22068 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22069
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22070 @sp 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22071
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22072 @noindent
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22073 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
22074
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22075 @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
22076 @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
22077
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22078 @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
22079 @sp 1
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22080
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22081 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
22082 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
22083 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
22084 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
22085 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
22086 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
22087
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22088 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
22089 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
22090 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
22091 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
22092
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22093 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
22094 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
22095 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
22096 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
22097
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22098 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
22099 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
22100 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
22101 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
22102 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
22103 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
22104 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
22105 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
22106
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22107 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
22108 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
22109
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22110 @c (texinfo)uref
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22111 (The Free Software Foundation
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22112 @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
22113 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
22114 GNU manuals}, too.)
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22115
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22116 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
22117 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
22118 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
22119 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
22120 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
22121 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
22122 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
22123 problems.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22124
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22125 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
22126 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
22127 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
22128 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
22129 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
22130
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22131 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
22132 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
22133 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
22134 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
22135 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
22136 views.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22137
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22138 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
22139 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
22140 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
22141 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
22142 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
22143 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
22144 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
22145 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
22146
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22147 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
22148 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
22149 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
22150 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
22151 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
22152 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
22153 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
22154 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
22155
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22156 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
22157 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
22158 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
22159 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
22160
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22161 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
22162 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
22163 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
22164 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
22165
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22166 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
22167 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
22168 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
22169 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
22170 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
22171
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22172 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
22173 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
22174 change that.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22175
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22176 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
22177 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
22178 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
22179 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
22180 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
22181 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
22182
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22183 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
22184 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
22185 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
22186 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
22187 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
22188
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22189 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
22190 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
22191 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
22192 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
22193
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22194 @sp 2
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22195 @noindent
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22196 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
22197 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
22198 @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
22199
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22200 @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
22201 @appendix GNU Free Documentation License
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22202
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22203 @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
22204 @center Version 1.2, November 2002
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22205
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22206 @display
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22207 Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc.
64091
6fb026ad601f Update FSF's address.
Lute Kamstra <lute@gnu.org>
parents: 64083
diff changeset
22208 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
22209
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22210 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
22211 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
22212 @end display
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22213
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22214 @enumerate 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22215 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22216 PREAMBLE
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22217
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22218 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
22219 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
22220 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
22221 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
22222 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
22223 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
22224 for modifications made by others.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22225
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22226 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
22227 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
22228 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
22229 license designed for free software.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22230
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22231 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
22232 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
22233 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
22234 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
22235 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
22236 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
22237 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
22238
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22239 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22240 APPLICABILITY AND DEFINITIONS
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22241
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22242 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
22243 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
22244 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
22245 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
22246 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
22247 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
22248 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
22249 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
22250 under copyright law.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22251
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22252 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
22253 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
22254 modifications and/or translated into another language.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22255
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22256 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
22257 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
22258 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
22259 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
22260 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
22261 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
22262 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
22263 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
22264 commercial, philosophical, ethical or political position regarding
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22265 them.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22266
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22267 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
22268 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
22269 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
22270 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
22271 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
22272 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
22273 Sections then there are none.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22274
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22275 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
22276 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
22277 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
22278 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
22279
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22280 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
22281 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
22282 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
22283 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
22284 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
22285 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
22286 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
22287 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
22288 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
22289 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
22290 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
22291 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
22292
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22293 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
22294 @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
22295 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
22296 @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
22297 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
22298 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
22299 @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
22300 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
22301 @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
22302 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
22303 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
22304 output purposes only.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22305
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22306 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
22307 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
22308 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
22309 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
22310 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
22311 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
22312
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22313 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
22314 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
22315 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
22316 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
22317 ``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
22318 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
22319 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
22320
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22321 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
22322 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
22323 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
22324 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
22325 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
22326 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
22327
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22328 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22329 VERBATIM COPYING
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22330
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22331 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
22332 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
22333 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
22334 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
22335 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
22336 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
22337 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
22338 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
22339 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
22340
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22341 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
22342 you may publicly display copies.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22343
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22344 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22345 COPYING IN QUANTITY
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22346
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22347 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
22348 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
22349 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
22350 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
22351 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
22352 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
22353 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
22354 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
22355 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
22356 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
22357 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
22358 as verbatim copying in other respects.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22359
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22360 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
22361 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
22362 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
22363 pages.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22364
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22365 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
22366 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
22367 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
22368 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
22369 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
22370 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
22371 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
22372 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
22373 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
22374 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
22375 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
22376 edition to the public.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22377
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22378 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
22379 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
22380 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
22381
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22382 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22383 MODIFICATIONS
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22384
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22385 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
22386 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
22387 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
22388 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
22389 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
22390 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
22391
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22392 @enumerate A
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22393 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22394 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
22395 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
22396 (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
22397 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
22398 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
22399
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22400 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22401 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
22402 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
22403 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
22404 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
22405 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
22406
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22407 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22408 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
22409 Modified Version, as the publisher.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22410
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22411 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22412 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
22413
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22414 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22415 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
22416 adjacent to the other copyright notices.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22417
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22418 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22419 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
22420 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
22421 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
22422
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22423 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22424 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
22425 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
22426
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22427 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22428 Include an unaltered copy of this License.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22429
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22430 @item
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22431 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
22432 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
22433 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
22434 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
22435 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
22436 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
22437 Version as stated in the previous sentence.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22438
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22439 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22440 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
22441 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
22442 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
22443 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
22444 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
22445 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
22446 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
22447
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22448 @item
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22449 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
22450 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
22451 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
22452 dedications given therein.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22453
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22454 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22455 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
22456 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
22457 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
22458
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22459 @item
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22460 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
22461 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
22462
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22463 @item
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22464 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
22465 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
22466
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22467 @item
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22468 Preserve any Warranty Disclaimers.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22469 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22470
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22471 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
22472 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
22473 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
22474 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
22475 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
22476 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
22477
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22478 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
22479 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
22480 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
22481 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
22482 standard.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22483
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22484 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
22485 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
22486 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
22487 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
22488 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
22489 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
22490 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
22491 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
22492 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
22493
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22494 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
22495 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
22496 imply endorsement of any Modified Version.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22497
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22498 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22499 COMBINING DOCUMENTS
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22501 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
22502 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
22503 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
22504 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
22505 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
22506 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
22507
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22508 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
22509 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
22510 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
22511 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
22512 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
22513 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
22514 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
22515 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
22516
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22517 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
22518 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
22519 ``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
22520 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
22521 sections Entitled ``Endorsements.''
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22522
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22523 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22524 COLLECTIONS OF DOCUMENTS
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22525
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22526 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
22527 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
22528 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
22529 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
22530 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
22531
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22532 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
22533 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
22534 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
22535 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
22536
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22537 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22538 AGGREGATION WITH INDEPENDENT WORKS
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22539
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22540 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
22541 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
22542 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
22543 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
22544 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
22545 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
22546 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
22547 derivative works of the Document.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22548
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22549 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
22550 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
22551 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
22552 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
22553 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
22554 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
22555 aggregate.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22556
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22557 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22558 TRANSLATION
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22559
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22560 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
22561 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
22562 Replacing Invariant Sections with translations requires special
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22563 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
22564 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
22565 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
22566 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
22567 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
22568 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
22569 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
22570 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
22571 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
22572
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22573 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
22574 ``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
22575 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
22576 title.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22577
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22578 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22579 TERMINATION
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22580
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22581 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
22582 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
22583 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
22584 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
22585 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
22586 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
22587 parties remain in full compliance.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22588
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22589 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22590 FUTURE REVISIONS OF THIS LICENSE
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22591
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22592 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
22593 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
22594 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
22595 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
22596 @uref{http://www.gnu.org/copyleft/}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22597
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22598 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
22599 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
22600 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
22601 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
22602 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
22603 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
22604 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
22605 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
22606 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22607
51945
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22608 @page
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22609 @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
22610
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22611 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
22612 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
22613 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
22614
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22615 @smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22616 @group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22617 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
22618 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
22619 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
22620 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
22621 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
22622 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
22623 Free Documentation License''.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22624 @end group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22625 @end smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22626
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22627 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
22628 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
22629
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22630 @smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22631 @group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22632 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
22633 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
22634 being @var{list}.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22635 @end group
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22636 @end smallexample
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22637
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22638 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
22639 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
22640 situation.
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22641
bfb22215769d Revise various segments, fix typos, add GNU Press information,
Robert J. Chassell <bob@rattlesnake.com>
parents: 50622
diff changeset
22642 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
22643 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
22644 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
22645 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
22646
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22647 @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
22648 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22649 @unnumbered Index
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22650
41670
b4c633081255 (Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents: 41499
diff changeset
22651 @ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22652 MENU ENTRY: NODE NAME.
41670
b4c633081255 (Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents: 41499
diff changeset
22653 @end ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22654
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22655 @printindex cp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22656
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22657 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22658 @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
22659
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22660 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22661 \ifodd\pageno
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22662 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22663 \global\evenheadline={\hfil} \global\evenfootline={\hfil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22664 \global\oddheadline={\hfil} \global\oddfootline={\hfil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22665 \page\hbox{}\page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22666 \else
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22667 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22668 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22669 \global\evenheadline={\hfil} \global\evenfootline={\hfil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22670 \global\oddheadline={\hfil} \global\oddfootline={\hfil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22671 \page\hbox{}\page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22672 \page\hbox{}\page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22673 \fi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22674 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22675
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22676 @page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22677 @w{ }
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22678
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22679 @c ================ Biographical information ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22680
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22681 @w{ }
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22682 @sp 8
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22683 @center About the Author
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22684 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22685 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22686
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22687 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22688 @node About the Author, , Index, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22689 @unnumbered About the Author
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22690 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22691
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22692 @quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22693 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
22694 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
22695 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
22696 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
22697 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
22698 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
22699 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
22700 airplane.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22701 @end quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22702
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22703 @page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22704 @w{ }
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22705
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22706 @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
22707 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22708 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22709 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22710
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22711 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22712 @headings off
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22713 @evenheading @thispage @| @| @thistitle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22714 @oddheading @| @| @thispage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22715 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22716
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22717 @bye
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 51945
diff changeset
22718
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 51945
diff changeset
22719 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 51945
diff changeset
22720 arch-tag: da1a2154-531f-43a8-8e33-fc7faad10acf
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 51945
diff changeset
22721 @end ignore